OpenAPI

Traduza os campos explicativos de ficheiros YAML OpenAPI 3.x sem alterar os caminhos, os identificadores de operação e as referências.

Um documento OpenAPI combina um contrato de API legível por máquina com explicações para quem o utiliza. O processador de ficheiros yaml-openapi seleciona os campos title, description e summary consoante a sua localização no YAML OpenAPI 3.x. Os caminhos, os IDs de operação e as referências mantêm-se inalterados.

Mantenha o contrato da API estável #

Neste exemplo, a operação mantém a sua identidade, enquanto a explicação pode ser traduzida para outros idiomas:

yaml
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 retrieved

O processador seleciona o título, o resumo e a descrição da resposta. /orders, listOrders e 1.0.0 mantêm-se inalterados. A seleção abrange também campos de informação, descrições de etiquetas e de documentação externa, descrições de caminhos e campos descritivos dentro de contentores reconhecidos de esquemas e operações.

Verifique os exemplos e os valores predefinidos que sejam objetos nesses contentores. Uma propriedade aninhada com o nome title, description ou summary também pode ser selecionada, mesmo quando representa dados de exemplo da carga útil. Outros valores do esquema, como cadeias de caracteres comuns de enumerações e valores de $ref, mantêm-se inalterados.

O analisador exige um mapeamento YAML com uma versão openapi que comece por 3.. São rejeitados documentos Swagger 2.x, documentos sem versão e documentos com outras versões. Um ficheiro OpenAPI em JSON não é selecionado só porque o OpenAPI permite 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 com o texto existente é estabelecida com base na identidade e na ocorrência dos campos descritivos, e a identidade da operação também contribui para o alinhamento. As descrições alteradas na origem exigem uma nova tradução; os campos correspondentes que se mantêm inalterados podem reutilizar o texto de destino.

O serializador YAML reconstrói o documento e pode normalizar a formatação. Mantenha as versões anteriores das especificações de origem e de destino alinhadas e verifique as mudanças de posição dos campos ou as 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 ficheiros da CLI. A extensão, por si só, não permite distinguir uma especificação de API de um catálogo de aplicação. O YAML genérico selecionaria muitas mais cadeias de caracteres; o YAML com raiz por idioma exige uma estrutura envolvente diferente.

Utilize a Configuração da CLI ou o GitHub para selecionar ficheiros e definir os caminhos de destino. A tradução limitada a chaves específicas através da CLI não está disponível para OpenAPI.

Valide o contrato e leia as descrições #

Valide o documento reconstruído com as suas ferramentas OpenAPI e compare os caminhos, os IDs de operação, as referências, os campos obrigatórios e os valores do esquema com os da origem. Depois, leia as descrições tal como são apresentadas, em conjunto com esse contrato. Uma descrição de resposta que altere uma condição ou uma garantia pode induzir um programador em erro, mesmo que a especificação continue válida.