Pular para o conteúdo

Visualizador e validador de OpenAPI e Swagger — YAML ou JSON

Cole uma especificação OpenAPI 3.x ou Swagger 2.0 para navegar por ela como documentação agrupada por tag, verificar erros estruturais e obter um exemplo de cURL por endpoint.

OpenAPI 3.0 · Bookstore API 1.2.0 · 4 operações · 1 erro, 0 aviso

Validação

  • Erro O path usa {itemId}, mas nenhum parâmetro in: path chamado “itemId” foi declarado.
    em paths./orders/{orderId}/items/{itemId}.get
O que é verificado

O visualizador verifica estas regras estruturais das especificações OpenAPI 3.0 / 3.1 e Swagger 2.0. Não é uma validação completa do documento com JSON Schema: palavras-chave individuais de schema (minimum, pattern, format…) não são verificadas.

  • O documento é YAML ou JSON válido.
  • Ele declara openapi: 3.0.x ou 3.1.x, ou swagger: "2.0".
  • info existe, com title e version (strings).
  • paths existe (opcional no 3.1 quando há components ou webhooks).
  • Todo path começa com /.
  • Os path items contêm só métodos HTTP, parameters, $ref, summary, description, servers (ou extensões x-).
  • Toda operação tem responses (erro no 2.0 e no 3.0, aviso no 3.1).
  • responses não está vazio.
  • As chaves de resposta são códigos de status (200), default ou (3.x) faixas como 2XX.
  • Toda resposta tem description.
  • Os valores de operationId são únicos.
  • Todo {name} em um path tem um parâmetro in: path correspondente.
  • Todo parâmetro in: path aparece no path.
  • Os parâmetros de path têm required: true.
  • Todo parâmetro tem name e in.
  • in é query, header, path ou cookie (2.0: query, header, path, formData ou body).
  • Nenhum parâmetro aparece duas vezes com o mesmo name e in.
  • Os parâmetros têm schema ou content (2.0: parâmetros body têm schema, os outros um type).
  • 2.0: no máximo um parâmetro body, e não junto com formData.
  • 3.x: requestBody tem content.
  • Todo $ref local (#/…) aponta para algo que existe.
  • Referências a outros arquivos ou URLs são informadas (elas não são baixadas).
  • Os requisitos de segurança citam um esquema de segurança definido.

Documentação: Bookstore API 1.2.0

A small example API. Edit it or paste your own spec.

URL base: https://api.example-bookstore.com/v1

Books

Browse and manage the catalogue

GET/booksList books
POST/booksAdd a book
GET/books/{bookId}Get one book

Orders

Place and track orders

GET/orders/{orderId}/items/{itemId}Get an order line

Schemas

NewBook
Book
Author
OrderItem

Funciona inteiramente no seu navegador. A sua especificação de API nunca é enviada, e $refs externos não são baixados. Ver todas as ferramentas grátis.

Encontrou um problema ou algo que poderia ser melhor? Lemos todas as mensagens e corrigimos rápido.

Este visualizador e validador de OpenAPI lê um documento OpenAPI 3.0, 3.1 ou Swagger 2.0 em YAML ou JSON e o mostra como documentação de API navegável: cada endpoint agrupado por tag, com seus parâmetros, corpo da requisição, respostas e schemas, além de um comando cURL pronto para rodar. Cole a especificação ou abra o arquivo; nada é enviado, então APIs internas e ainda não lançadas continuam privadas.

O validador executa 23 verificações estruturais tiradas das especificações, todas listadas na página: info e paths presentes, respostas com descrição e códigos de status válidos, todo {parameter} de um path declarado como parâmetro de path obrigatório, operationIds únicos, $refs que se resolvem e requisitos de segurança que citam um esquema definido. São os erros que quebram geradores de código e ferramentas de documentação. Não é uma validação completa contra o JSON Schema oficial da especificação, então uma especificação aprovada aqui ainda pode ter, por exemplo, uma palavra-chave de schema escrita errado. $refs externos para outros arquivos são listados, mas não baixados.

Como usar

  1. Cole o seu openapi.yaml, openapi.json ou swagger.json, ou abra o arquivo. Uma API de exemplo é carregada para começar.
  2. Leia a linha de status e a lista de Validação. Cada problema cita a regra e onde ele está (por exemplo, paths./pets/{id}.get).
  3. Navegue pela documentação: as operações são agrupadas por tag; clique em uma para ver parâmetros, corpo da requisição, respostas e schemas.
  4. Filtre por path, resumo ou operationId para encontrar um endpoint em uma especificação grande.
  5. Copie o exemplo de cURL de uma operação e substitua o placeholder <TOKEN> ou <API_KEY> pelas suas credenciais.

Perguntas frequentes

Como visualizar um arquivo Swagger ou OpenAPI?

Cole o YAML ou JSON na caixa ou abra o arquivo. O visualizador detecta a versão (swagger: "2.0" ou openapi: 3.0.x / 3.1.x), lista os endpoints agrupados por tag e permite expandir cada um para ver os parâmetros, o corpo da requisição, as respostas e os schemas resolvidos. Depois que a página carrega, ele funciona offline.

O que o validador de OpenAPI verifica?

Regras estruturais da especificação: um campo de versão suportado; info com title e version; paths começando com /; operações com responses não vazio, com descrições e códigos de status válidos; parâmetros do template de path declarados e obrigatórios; parâmetros com name, um in válido e um schema; nenhum parâmetro ou operationId duplicado; corpos de requisição com content; $refs que se resolvem; e requisitos de segurança que citam esquemas definidos. A lista completa está na página, em “O que é verificado”. Ele não valida cada palavra-chave de schema contra o JSON Schema oficial.

Por que o meu parâmetro de path não declarado é um erro?

A especificação exige que todo {name} em um template de path tenha um parâmetro correspondente com in: path e required: true, no nível do path ou da operação. Alguns validadores que só conferem o documento contra o JSON Schema aceitam a falta dele, mas aí os geradores de código produzem uma função sem argumento para ele, e as ferramentas de documentação mostram um endpoint que você não consegue chamar corretamente.

Ele lê OpenAPI 3.1 e Swagger 2.0?

Sim. Os parâmetros body e formData do Swagger 2.0 aparecem como corpo da requisição, com produces e consumes como media types, então as três versões são lidas da mesma forma. As diferenças do OpenAPI 3.1 são respeitadas: paths é opcional quando há components ou webhooks, responses é opcional (aqui, um aviso) e type: [string, "null"] aparece como nullable.

Ele carrega arquivos $ref externos?

Não. Um $ref para outro arquivo ou URL (por exemplo ./schemas/user.yaml) é listado como aviso e mostrado como não resolvido, porque a página não consegue ler arquivos que você não abriu e não baixa URLs por conta própria. Junte antes uma especificação de vários arquivos em um único documento, por exemplo com redocly bundle ou swagger-cli bundle.

A minha especificação de API é enviada?

Não. A análise, a validação e a renderização acontecem no seu navegador. A especificação nunca é enviada a lugar nenhum.

OpenAPI 3.x e Swagger 2.0: o que mudou

• Campo de versão: swagger: "2.0" virou openapi: 3.0.x e depois 3.1.x.

• Servidores: o 2.0 tem host, basePath e schemes; o 3.x tem uma lista servers com variáveis.

• Corpos de requisição: o 2.0 usa um parâmetro com in: body (ou formData); o 3.x tem requestBody com content por media type.

• Partes reutilizáveis: no 2.0, definitions, parameters e responses ficam no nível superior; o 3.x as coloca em components, junto com securitySchemes, requestBodies e examples.

• O 3.1 alinha os schemas com o JSON Schema 2020-12: type pode ser uma lista (["string", "null"] em vez de nullable: true), examples é um array, e foram adicionados os webhooks.

Os erros que mais quebram ferramentas de API

• Parâmetros de path não declarados, ou declarados sem required: true.

• Um $ref com erro de digitação (#/components/schema/User em vez de schemas), que deixa parte da documentação vazia.

• operationIds duplicados, que fazem os geradores de código falhar ou sobrescrever métodos.

• Respostas sem description (ela é obrigatória, mesmo que seja só "OK").

• Um requisito de segurança que cita um esquema não definido, de modo que o cliente gerado não tem como se autenticar.