OpenAPI
Traduza campos explicativos em YAML OpenAPI 3.x sem alterar caminhos, identificadores de operação ou referências.
Um documento OpenAPI combina um contrato de API legível por máquina com explicações para quem usa a API. O processador de arquivos yaml-openapi seleciona os campos title, description e summary de acordo com sua localização no YAML OpenAPI 3.x. Caminhos, IDs de operação e referências permanecem inalterados.
Mantenha o contrato da API estável #
Neste exemplo, a operação mantém sua identidade, enquanto a explicação pode ser traduzida para outros idiomas:
openapi: 3.0.3
info:
title: Order service
version: 1.0.0
paths:
/orders:
get:
operationId: listOrders
summary: List your orders
responses:
"200":
description: Orders retrievedO processador seleciona o título, o resumo e a descrição da resposta. /orders, listOrders e 1.0.0 permanecem inalterados. A seleção também abrange campos de informações, descrições de tags e de documentação externa, descrições de caminhos e campos descritivos em contêineres reconhecidos de esquemas e operações.
Verifique os exemplos e valores padrão definidos como objetos nesses contêineres. Uma propriedade aninhada chamada title, description ou summary também pode ser selecionada, mesmo quando representa dados de exemplo enviados em uma requisição. Outros valores do esquema, como strings comuns de enumeração e valores de $ref, permanecem inalterados.
O analisador exige um mapeamento YAML com uma versão de openapi que comece com 3.. Documentos Swagger 2.x, sem versão ou com outras versões são rejeitados. Um arquivo OpenAPI em JSON não é selecionado só porque o OpenAPI aceita JSON; o contrato deste processador exige YAML.
Reconstrução e reutilização #
O documento de origem atual define a árvore da especificação. A correspondência dos textos existentes é feita pela identidade e pela ocorrência dos campos descritivos, e a identidade da operação também contribui para o alinhamento. Descrições alteradas na origem precisam de uma nova tradução; campos correspondentes que não mudaram podem reutilizar o texto de destino.
O serializador YAML reconstrói o documento e pode normalizar a formatação. Mantenha alinhadas as especificações anteriores de origem e destino e verifique se há campos que mudaram de lugar ou descrições repetidas que afetem a reutilização.
Selecione o processador de especificações #
Selecione explicitamente yaml-openapi para .yaml ou .yml na configuração de arquivos da CLI. A extensão, por si só, não distingue uma especificação de API de um catálogo de aplicação. O YAML genérico selecionaria muito mais strings; o YAML com idioma na raiz exige uma estrutura externa diferente.
Use a configuração da CLI ou o GitHub para selecionar arquivos e definir os caminhos de destino. A tradução com escopo por chave na CLI não está disponível para OpenAPI.
Valide o contrato e leia as descrições #
Valide o documento reconstruído com suas ferramentas OpenAPI e compare caminhos, IDs de operação, referências, campos obrigatórios e valores do esquema com o documento de origem. Depois, leia as descrições renderizadas em conjunto com esse contrato. Uma descrição de resposta que altere uma condição ou promessa pode induzir um desenvolvedor ao erro, mesmo que a especificação continue válida.