// Gere documentação abrangente e amigável para desenvolvedores a partir do código, incluindo endpoints, parâmetros, exemplos e melhores práticas
| name | api-documentation-generator |
| description | Gere documentação abrangente e amigável para desenvolvedores a partir do código, incluindo endpoints, parâmetros, exemplos e melhores práticas |
Gere automaticamente documentação clara e abrangente de API a partir do seu código-fonte. Esta skill ajuda você a criar documentação profissional que inclui descrições de endpoints, exemplos de requisição/resposta, detalhes de autenticação, tratamento de erros e diretrizes de uso.
Perfeita para APIs REST, GraphQL e WebSocket.
Primeiro, examinarei seu código de API para entender:
Para cada endpoint, criarei documentação incluindo:
Detalhes do Endpoint:
Especificação de Requisição:
Especificação de Resposta:
Exemplos de Código:
Incluirei:
Documentação clara de erros incluindo:
Quando possível, fornecerei:
## Criar Usuário
Cria uma nova conta de usuário.
**Endpoint:** `POST /api/v1/users`
**Autenticação:** Obrigatória (token Bearer)
**Corpo da Requisição:**
\`\`\`json
{
"email": "user@example.com", // Obrigatório: Endereço de email válido
"password": "SecurePass123!", // Obrigatório: Min 8 caracteres, 1 maiúscula, 1 número
"name": "John Doe", // Obrigatório: 2-50 caracteres
"role": "user" // Opcional: "user" ou "admin" (padrão: "user")
}
\`\`\`
**Resposta de Sucesso (201 Created):**
\`\`\`json
{
"id": "usr_1234567890",
"email": "user@example.com",
"name": "John Doe",
"role": "user",
"createdAt": "2026-01-20T10:30:00Z",
"emailVerified": false
}
\`\`\`
**Respostas de Erro:**
- `400 Bad Request` - Dados de entrada inválidos
\`\`\`json
{
"error": "VALIDATION_ERROR",
"message": "Formato de email inválido",
"field": "email"
}
\`\`\`
- `409 Conflict` - Email já existe
\`\`\`json
{
"error": "EMAIL_EXISTS",
"message": "Já existe uma conta com este email"
}
\`\`\`
- `401 Unauthorized` - Token de autenticação ausente ou inválido
**Exemplo de Requisição (cURL):**
\`\`\`bash
curl -X POST https://api.example.com/api/v1/users \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePass123!",
"name": "John Doe"
}'
\`\`\`
**Exemplo de Requisição (JavaScript):**
\`\`\`javascript
const response = await fetch('https://api.example.com/api/v1/users', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'user@example.com',
password: 'SecurePass123!',
name: 'John Doe'
})
});
const user = await response.json();
console.log(user);
\`\`\`
**Exemplo de Requisição (Python):**
\`\`\`python
import requests
response = requests.post(
'https://api.example.com/api/v1/users',
headers={
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
},
json={
'email': 'user@example.com',
'password': 'SecurePass123!',
'name': 'John Doe'
}
)
user = response.json()
print(user)
\`\`\`
## Consulta de Usuário
Busca informações do usuário por ID.
**Consulta:**
\`\`\`graphql
query GetUser($id: ID!) {
user(id: $id) {
id
email
name
role
createdAt
posts {
id
title
publishedAt
}
}
}
\`\`\`
**Variáveis:**
\`\`\`json
{
"id": "usr_1234567890"
}
\`\`\`
**Resposta:**
\`\`\`json
{
"data": {
"user": {
"id": "usr_1234567890",
"email": "user@example.com",
"name": "John Doe",
"role": "user",
"createdAt": "2026-01-20T10:30:00Z",
"posts": [
{
"id": "post_123",
"title": "Meu Primeiro Post",
"publishedAt": "2026-01-21T14:00:00Z"
}
]
}
}
}
\`\`\`
**Erros:**
\`\`\`json
{
"errors": [
{
"message": "Usuário não encontrado",
"extensions": {
"code": "USER_NOT_FOUND",
"userId": "usr_1234567890"
}
}
]
}
\`\`\`
## Autenticação
Todas as requisições de API requerem autenticação usando tokens Bearer.
### Obter um Token
**Endpoint:** `POST /api/v1/auth/login`
**Requisição:**
\`\`\`json
{
"email": "user@example.com",
"password": "sua-senha"
}
\`\`\`
**Resposta:**
\`\`\`json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600,
"refreshToken": "refresh_token_here"
}
\`\`\`
### Usar o Token
Inclua o token no header de Authorization:
\`\`\`
Authorization: Bearer YOUR_TOKEN
\`\`\`
### Expiração do Token
Os tokens expiram após 1 hora. Use o refresh token para obter um novo token de acesso:
**Endpoint:** `POST /api/v1/auth/refresh`
**Requisição:**
\`\`\`json
{
"refreshToken": "refresh_token_here"
}
\`\`\`
Introdução
Autenticação
Início Rápido
Endpoints
Modelos de Dados
Tratamento de Erros
Limite de Taxa
Changelog
SDKs e Ferramentas
Sintomas: Exemplos não funcionam, parâmetros estão errados, endpoints retornam dados diferentes Solução:
Sintomas: Usuários não sabem como lidar com erros, tickets de suporte aumentam Solução:
Sintomas: Usuários não conseguem começar, frustração aumenta Solução:
Sintomas: Usuários enviam requisições inválidas, erros de validação Solução:
Gere documentação interativa:
openapi: 3.0.0
info:
title: Minha API
version: 1.0.0
paths:
/users:
post:
summary: Criar um novo usuário
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
Exporte coleção para teste fácil:
{
"info": {
"name": "Minha API",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Criar Usuário",
"request": {
"method": "POST",
"url": "{{baseUrl}}/api/v1/users"
}
}
]
}
@doc-coauthoring - Para escrita colaborativa de documentação@copywriting - Para descrições claras e amigáveis ao usuário@test-driven-development - Para garantir que o comportamento de API corresponda à documentação@systematic-debugging - Para resolução de problemas de APIDica Pro: Mantenha sua documentação de API o mais próximo possível do seu código. Use ferramentas que gerem documentação a partir de comentários de código para garantir que fiquem sincronizadas!