Habilidades openapi-spec-generation
📦

openapi-spec-generation

Seguro 🌐 Acesso à rede⚙️ Comandos externos

Gerar Especificações OpenAPI 3.1

Criar e manter documentação de API é demorado e propenso a erros. Esta skill oferece templates abrangentes, exemplos de código e padrões de validação para especificações OpenAPI 3.1 para agilizar os fluxos de trabalho de documentação de API.

Suporta: Claude Codex Code(CC)
📊 69 Adequado
1

Baixar o ZIP da skill

2

Upload no Claude

Vá em Configurações → Capacidades → Skills → Upload skill

3

Ative e comece a usar

Testar

A utilizar "openapi-spec-generation". Crie uma especificação OpenAPI para uma API de catálogo de produtos

Resultado esperado:

  • openapi: 3.1.0 com seção info contendo título, descrição, versão
  • Endpoints GET/POST/PUT/DELETE para recurso de produtos
  • Schema de produto com propriedades id, nome, preço, descrição, categoria
  • Parâmetros de query para paginação e filtragem
  • Respostas de erro para códigos de status 400 404, 429
  • , 401,Configuração de autenticação Bearer token em schemes de segurança

A utilizar "openapi-spec-generation". Escreva regras de validação Spectral para operationIds

Resultado esperado:

  • Regra verifica presença de operationId em cada operação
  • Nível de severidade definido como erro para operationId faltante
  • Valida que operationId segue padrão de convenção de nomes
  • Reporta violações com caminho do campo e mensagem descritiva

Auditoria de Segurança

Seguro
v4 • 1/17/2026

Pure documentation skill containing YAML OpenAPI templates, code examples (Python FastAPI, TypeScript tsoa), and validation patterns. No executable code, no file system access, no network calls. All 126 static findings are false positives: detected cryptographic keywords are data format specifiers in YAML schemas, backticks are markdown formatting in documentation code blocks, URLs are example domains and documentation references, and system keywords are standard OpenAPI syntax.

2
Arquivos analisados
1,207
Linhas analisadas
2
achados
4
Total de auditorias

Fatores de risco

🌐 Acesso à rede (13)
skill-report.json:6 SKILL.md:29 SKILL.md:67 SKILL.md:70 SKILL.md:73 SKILL.md:75 SKILL.md:77 SKILL.md:533 SKILL.md:534 SKILL.md:1025 SKILL.md:1026 SKILL.md:1027 SKILL.md:1028
⚙️ Comandos externos (11)
SKILL.md:23-36 SKILL.md:36-50 SKILL.md:50-511 SKILL.md:511-515 SKILL.md:515-701 SKILL.md:701-705 SKILL.md:705-893 SKILL.md:893-897 SKILL.md:897-978 SKILL.md:978-982 SKILL.md:982-1005
Auditado por: claude Ver Histórico de Auditoria →

Pontuação de qualidade

38
Arquitetura
100
Manutenibilidade
87
Conteúdo
30
Comunidade
100
Segurança
78
Conformidade com especificações

O Que Você Pode Construir

Criar Especificações de API

Projete e documente APIs REST com templates completos OpenAPI 3.1 incluindo schemas, exemplos e esquemas de segurança.

Documentação Code-First

Gere specs OpenAPI a partir de codebases FastAPI ou Express/tsoa existentes para geração automática de SDK.

Validar Contratos de API

Configure regras de linting e pipelines de validação para garantir que especificações de API atendam aos padrões de qualidade e conformidade.

Tente Estes Prompts

Spec Básica 
Gere um template de especificação OpenAPI 3.1 para uma API de [RECURSO] com endpoints CRUD, autenticação e respostas de erro.
Code-First 
Crie um exemplo de código Python FastAPI que gera uma especificação OpenAPI para gerenciamento de usuários com paginação e filtragem.
Validação 
Escreva regras de validação Spectral para specs OpenAPI que imponham operationIds, descrições e definições de segurança.
Geração de SDK 
Gere um comando do OpenAPI Generator para criar um cliente TypeScript a partir de um arquivo de especificação OpenAPI.

Melhores Práticas

  • Use $ref para schemas, parâmetros e respostas reutilizáveis para manter consistência entre especificações
  • Inclua exemplos reais em schemas de request e response para ajudar consumidores de API a entenderem o uso
  • Defina todas as possíveis respostas de erro incluindo erros de validação, falhas de autenticação e rate limiting

Evitar

  • Evite descrições genéricas ou ausentes em operações, parâmetros e propriedades de schema
  • Não pule a definição de schemes de segurança mesmo para APIs internas
  • Evite hardcoding de URLs de servidor em paths; use variáveis de servidor para diferentes ambientes

Perguntas Frequentes

Quais linguagens de programação esta skill suporta?
Templates cobrem Python FastAPI, TypeScript com tsoa, e YAML puro para qualquer linguagem. Geração de SDK suporta mais de 50 linguagens.
Quais são os limites de tamanho para especificações OpenAPI?
Specs OpenAPI não têm limite rígido de tamanho, mas ferramentas podem ter limites práticos. Specs grandes devem ser divididas usando $ref para manutenibilidade.
Como integrar com pipelines de CI/CD?
Use Spectral CLI ou Redocly no CI para validar specs. Adicione pre-commit hooks para garantir que especificações passem linting antes do deploy.
Meus dados de especificação de API são mantidos privados?
Esta skill executa localmente sem acesso à rede. Suas especificações permanecem na sua máquina e nunca são transmitidas externamente.
Por que minha especificação não está gerando os endpoints esperados?
Verifique que paths seguem formato OpenAPI com métodos HTTP aninhados sob path items. Verifique que schemas são referenciados corretamente com $ref.
Como isso se compara ao Swagger Editor?
Swagger Editor fornece edição interativa. Esta skill fornece templates e padrões que você pode copiar para qualquer editor ou pipeline de CI.

Detalhes do Desenvolvedor

Autor

wshobson

Licença

MIT

Repositório

https://github.com/wshobson/agents/tree/main/plugins/documentation-generation/skills/openapi-spec-generation

Referência

main

Estrutura de arquivos

📄 SKILL.md