Validar especificações Swagger/OpenAPI
OpenAPI (anteriormente Swagger) é o padrão para descrever APIs RESTful. Esta ferramenta de lint OpenAPI analisa seus documentos para identificar problemas comuns de qualidade, garantindo contratos consistentes, fáceis de descobrir e simples de consumir por desenvolvedores.
Um documento OpenAPI define endpoints, métodos HTTP, parâmetros, request/response bodies, autenticação e componentes reutilizáveis em YAML ou JSON. Especificações claras e validadas impulsionam documentação automática, geração de código, testes e governança entre equipes.
O linter verifica descrições ausentes, status codes ambíguos, schemas inconsistentes e oportunidades de reutilização de componentes com $ref. Incentiva nomenclatura consistente, content types explícitos e exemplos completos, reduzindo atritos na geração de SDKs e integrações de clientes.
Considere um POST /users com requestBody sem schema ou exemplo. O lint identifica o problema e sugere adicionar um JSON Schema em components.schemas.User, referenciá-lo via $ref e documentar respostas 201 e 400 com exemplos de payload.
Cole sua especificação para obter feedback rápido. Use durante revisões de design e no CI/CD para manter specs legíveis e compatíveis com ferramentas. Combine com contract testing para garantir que implementações permaneçam alinhadas ao contrato.
Ecossistemas de API saudáveis começam com especificações de alta qualidade. Execute lint com frequência para gerar documentação e SDKs que desenvolvedores realmente apreciam.