Gerador de Documentação de API
Esta skill gera automaticamente documentação OpenAPI 3.0 (Swagger) a partir de arquivos de rota de API no seu código-fonte.
Quando Usar Esta Skill
- O usuário solicita gerar documentação de API
- Trabalhando com endpoints de API REST
- Necessidade de criar ou atualizar especificações OpenAPI/Swagger
- Configurando documentação de API para Express, FastAPI, Flask, NestJS ou frameworks similares
Instruções
1. Descobrir Rotas da API
Pesquise no código-fonte por definições de rota de API:
- Express/Node.js: Procure por
app.get(),app.post(),router.get(), etc. - FastAPI/Python: Procure por decoradores
@app.get(),@router.post() - Flask: Procure por decoradores
@app.route() - NestJS: Procure por decoradores
@Get(),@Post(),@Controller() - Rails: Procure por rotas em
config/routes.rb
Use Glob para encontrar arquivos de rota (ex.: **/*routes*.{js,ts,py}, **/controllers/**/*.{js,ts})
2. Analisar Padrões de Rota
Para cada rota descoberta, extraia:
- Método HTTP: GET, POST, PUT, PATCH, DELETE
- Caminho: URL do endpoint (ex.:
/api/users/:id) - Parâmetros: Parâmetros de caminho, parâmetros de consulta, corpo da requisição
- Resposta: Estrutura de resposta esperada
- Autenticação: Se a autenticação é necessária
- Descrição: Comentários ou docstrings próximos à rota
3. Gerar Especificação OpenAPI
Crie ou atualize um arquivo de especificação OpenAPI 3.0 (normalmente openapi.yaml ou swagger.json):
- Comece com o modelo de
templates/openapi-3.0.yaml - Mapeie cada rota para um objeto de caminho OpenAPI
- Defina schemas de requisição/resposta usando JSON Schema
- Inclua definições de parâmetros (caminho, consulta, corpo)
- Adicione esquemas de autenticação se detectados (Bearer, API Key, OAuth2)
- Agrupe endpoints por tags (ex.: "Usuários", "Produtos", "Auth")
4. Validar Completude
Verifique se a documentação gerada inclui:
- Todos os endpoints descobertos
- Métodos HTTP e caminhos precisos
- Exemplos de requisição/resposta quando possível
- Respostas de erro (400, 401, 404, 500, etc.)
- Requisitos de segurança
5. Local de Saída
- Salve como
openapi.yamlna raiz do projeto, ou - Coloque no diretório
docs/ouapi/se existirem - Pergunte ao usuário pelo local preferido se não estiver claro
Notas Específicas por Framework
Express/Node.js
- Verifique middlewares de rota que possam afetar autenticação/validação
- Procure por validadores de requisição (Joi, express-validator, etc.)
- Extraia comentários JSDoc para descrições de endpoint
FastAPI
- O FastAPI gera automaticamente documentação OpenAPI, mas esta skill pode aprimorá-la
- Extraia modelos Pydantic para schemas de requisição/resposta
- Verifique parâmetros
response_modelestatus_code
NestJS
- Procure por DTOs (Data Transfer Objects) para schemas
- Verifique decoradores Swagger (
@ApiOperation,@ApiResponse) - Extraia metadados de decoradores de controller e método
Melhores Práticas
- Use schemas existentes: Se o código-fonte possui interfaces TypeScript, modelos Pydantic ou similares, use-os para schemas precisos
- Inclua exemplos: Adicione exemplos de requisição/resposta de testes, se disponíveis
- Agrupe logicamente: Organize endpoints por recurso ou área de funcionalidade usando tags
- Versione adequadamente: Use a versão da API do código-fonte (ex.: "1.0.0")
- Adicione descrições: Use comentários de código/docstrings para descrições de endpoint
Arquivos de Suporte
templates/openapi-3.0.yaml: Modelo base OpenAPIexamples.md: Exemplos específicos por framework