Softonic

Verificação de campos obrigatórios do OpenAPI

Etapa 1 / 2
Próximo

Antes de entregar uma descrição de API a um colega, a um cliente ou a um gerador de documentação, garanta que os campos obrigatórios estão no lugar. Cole seu documento acima e a ferramenta confirma o campo de versão, info.title, info.version e paths, listando o que estiver faltando.

Como verificar os campos obrigatórios

  1. 1

    Cole o documento

    Cole sua spec em JSON ou YAML, mesmo que ainda esteja em andamento.

  2. 2

    Execute a verificação

    Avance para a etapa de resultados. Cada campo ausente aparece como um erro separado.

  3. 3

    Adicione o que falta

    Inclua no seu arquivo os campos listados usando os trechos abaixo.

  4. 4

    Verifique de novo

    Cole a spec atualizada e execute outra vez até não aparecer nenhum erro.

As quatro partes obrigatórias

Campo Onde fica Exemplo
Campo de versão Nível superior openapi: 3.0.3 ou swagger: "2.0"
info.title Dentro de info title: Orders API
info.version Dentro de info version: 1.0.0
paths Nível superior paths: com pelo menos a primeira rota

O valor de info.version é a versão da sua própria API, não da especificação OpenAPI. Muita gente deixa de fora porque a versão da especificação já aparece no topo.

Um exemplo prático com tudo ausente

servers:
  - url: https://api.example.com

Este documento minúsculo não tem nenhuma das partes obrigatórias. O relatório lista três erros:

Achado Tipo
Campo de versão ‘openapi’ ou ‘swagger’ ausente. Erro
Objeto ‘info’ ausente. Erro
Objeto ‘paths’ ausente. Erro

Quando o objeto info inteiro está ausente, a ferramenta informa esse único erro e não lista título e versão separadamente. Adicione info com os dois campos e a próxima execução informará se algum ainda estiver faltando.

Esqueleto inicial

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

Este esqueleto passa em todas as verificações de campos obrigatórios. Troque os nomes pelos seus e construa a partir daí. Respostas, schemas e segurança não fazem parte desta verificação.

Quando executar esta verificação

Execute quando começar uma spec do zero, depois de gerá-la a partir do código e antes de enviá-la a alguém que vá importá-la em outra ferramenta. Muitos importadores param no primeiro campo obrigatório ausente com uma mensagem curta, então capturar todos de uma vez economiza várias idas e vindas. É também um lembrete útil para quem está começando, que costuma esquecer info.version ou deixar paths de fora ao esboçar uma API.

Depois que os campos obrigatórios passarem, os próximos acréscimos úteis são uma description curta em info, uma entrada servers e um operationId em cada operação. Nenhum deles é verificado aqui, mas todos deixam a spec mais fácil de ler e de transformar em código cliente.

Perguntas frequentes

Não. O campo openapi indica qual versão da especificação você usa. info.version é a versão da sua própria API, como 1.0.0.

A chave precisa existir como objeto, e esta verificação não exige nenhuma rota dentro dele. Adicione rotas reais antes de publicar.

As verificações de título e versão só são executadas quando o objeto info existe. Adicione-o e execute de novo para ver se os campos estão completos.

Não. Aqui são exigidos apenas o campo de versão, info, title, version e paths. Detalhes no nível da operação não são examinados.

Ferramentas relacionadas

Contador de FPS

Meça o FPS do navegador com requestAnimationFrame: suavização, taxa de quadros mínima e máxima, limite de alerta e gráfico opcional. Roda localmente, sem upload nem API.

Gerador de Configuração Webpack

Crie um webpack.config.js para webpack 5 com JavaScript puro, React ou Vue: TypeScript, Babel, CSS ou Sass, imagens, HtmlWebpackPlugin, servidor de desenvolvimento e a linha de npm install.

Conversor de Tamanho de Arquivo

Converta entre bytes, KB, MB, GB, TB e as unidades binárias IEC (KiB, MiB, GiB, TiB), combinando decimal e binário como preferir.

Gerador de textura de ruído

Gere uma textura de ruído em SVG que se repete sem emendas, com opacidade, frequência do grão, tipo de ruído e cor de fundo ajustáveis, e copie o CSS já pronto.

Gerador de Licença

Gere o texto completo de licenças de código aberto com seu nome e ano preenchidos. Abrange licenças MIT, Apache 2.0, GPLv3, BSD-3, MPL-2.0 e CC.

Desofuscador de JavaScript

Desofusque JavaScript minificado ou empacotado com renomeação de variáveis, decodificação de arrays de strings, reversão de achatamento de fluxo de controle e embelezamento.

Ferramenta disponível em outros idiomas

Guias e casos de uso