- name
- api-documenter
- description
- Geração de documentação de APIs no padrão OpenAPI/Swagger a partir de código PHP/Laravel. Usar para documentar endpoints, gerar specs OpenAPI 3.0, criar documentação interativa, documentar autenticação, schemas de request/response, e integrar com ferramentas como Swagger UI, Redoc, ou Stoplight.
API Documenter
Skill para documentação de APIs RESTful no padrão OpenAPI 3.0.
Estrutura OpenAPI
openapi: 3.0.3
info:
title: Nome da API
description: Descrição detalhada
version: 1.0.0
contact:
name: Equipe de Desenvolvimento
email: [email protected]
servers:
- url: https://api.empresa.com/v1
description: Produção
- url: https://staging-api.empresa.com/v1
description: Staging
- url: http://localhost:8000/api/v1
description: Local
tags:
- name: Contratos
description: Gerenciamento de contratos
- name: Clientes
description: Gerenciamento de clientes
paths:
# Endpoints aqui
components:
# Schemas, Security, etc.Documentando Endpoints
CRUD Completo
paths:
/contracts:
get:
tags:
- Contratos
summary: Listar contratos
description: Retorna lista paginada de contratos com filtros opcionais
operationId: listContracts
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PerPageParam'
- name: status
in: query
description: Filtrar por status
schema:
type: string
enum: [pending, active, completed, cancelled]
- name: client_id
in: query
description: Filtrar por cliente
schema:
type: integer
- name: date_from
in: query
description: Data inicial (YYYY-MM-DD)
schema:
type: string
format: date
- name: date_to
in: query
description: Data final (YYYY-MM-DD)
schema:
type: string
format: date
responses:
'200':
description: Lista de contratos
content:
application/json:
schema:
$ref: '#/components/schemas/ContractPaginatedResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
tags:
- Contratos
summary: Criar contrato
description: Cria um novo contrato no sistema
operationId: createContract
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContractRequest'
example:
client_id: 1
event_date: "2024-06-15"
value: 5000.00
notes: "Evento corporativo"
responses:
'201':
description: Contrato criado com sucesso
content:
application/json:
schema:
$ref: '#/components/schemas/ContractResponse'
'422':
$ref: '#/components/responses/ValidationError'
/contracts/{id}:
get:
tags:
- Contratos
summary: Obter contrato
operationId: getContract
parameters:
- $ref: '#/components/parameters/ContractId'
responses:
'200':
description: Detalhes do contrato
content:
application/json:
schema:
$ref: '#/components/schemas/ContractResponse'
'404':
$ref: '#/components/responses/NotFound'
put:
tags:
- Contratos
summary: Atualizar contrato
operationId: updateContract
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/ContractId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateContractRequest'
responses:
'200':
description: Contrato atualizado
content:
application/json:
schema:
$ref: '#/components/schemas/ContractResponse'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ValidationError'
delete:
tags:
- Contratos
summary: Excluir contrato
operationId: deleteContract
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/ContractId'
responses:
'204':
description: Contrato excluído com sucesso
'404':
$ref: '#/components/responses/NotFound'Components (Schemas)
components:
schemas:
# Request Schemas
CreateContractRequest:
type: object
required:
- client_id
- event_date
- value
properties:
client_id:
type: integer
description: ID do cliente
example: 1
event_date:
type: string
format: date
description: Data do evento
example: "2024-06-15"
value:
type: number
format: float
minimum: 0.01
description: Valor do contrato
example: 5000.00
status:
type: string
enum: [pending, active]
default: pending
notes:
type: string
maxLength: 1000
description: Observações
nullable: true
UpdateContractRequest:
type: object
properties:
event_date:
type: string
format: date
value:
type: number
format: float
minimum: 0.01
status:
type: string
enum: [pending, active, completed, cancelled]
notes:
type: string
nullable: true
# Response Schemas
Contract:
type: object
properties:
id:
type: integer
example: 1
client_id:
type: integer
example: 1
event_date:
type: string
format: date
example: "2024-06-15"
event_date_formatted:
type: string
example: "15/06/2024"
value:
type: number
format: float
example: 5000.00
value_formatted:
type: string
example: "R$ 5.000,00"
status:
type: string
enum: [pending, active, completed, cancelled]
status_label:
type: string
example: "Pendente"
notes:
type: string
nullable: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
client:
$ref: '#/components/schemas/Client'
ContractResponse:
type: object
properties:
data:
$ref: '#/components/schemas/Contract'
ContractPaginatedResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Contract'
meta:
$ref: '#/components/schemas/PaginationMeta'
links:
$ref: '#/components/schemas/PaginationLinks'
# Pagination
PaginationMeta:
type: object
properties:
current_page:
type: integer
from:
type: integer
last_page:
type: integer
per_page:
type: integer
to:
type: integer
total:
type: integer
PaginationLinks:
type: object
properties:
first:
type: string
format: uri
last:
type: string
format: uri
prev:
type: string
format: uri
nullable: true
next:
type: string
format: uri
nullable: true
# Error Schemas
ValidationError:
type: object
properties:
message:
type: string
example: "The given data was invalid."
errors:
type: object
additionalProperties:
type: array
items:
type: string
example:
client_id: ["O campo cliente é obrigatório."]
value: ["O valor deve ser maior que zero."]
# Parameters
parameters:
ContractId:
name: id
in: path
required: true
description: ID do contrato
schema:
type: integer
PageParam:
name: page
in: query
description: Número da página
schema:
type: integer
default: 1
minimum: 1
PerPageParam:
name: per_page
in: query
description: Itens por página
schema:
type: integer
default: 15
minimum: 1
maximum: 100
# Responses
responses:
Unauthorized:
description: Não autenticado
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Unauthenticated."
NotFound:
description: Recurso não encontrado
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Contrato não encontrado."
ValidationError:
description: Erro de validação
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
# Security
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Token JWT obtido via login
apiKey:
type: apiKey
in: header
name: X-API-KeyIntegração Laravel com Annotations
/**
* @OA\Get(
* path="/api/contracts",
* tags={"Contratos"},
* summary="Listar contratos",
* @OA\Parameter(ref="#/components/parameters/PageParam"),
* @OA\Response(
* response=200,
* description="Lista de contratos",
* @OA\JsonContent(ref="#/components/schemas/ContractPaginatedResponse")
* )
* )
*/
public function index()
{
// ...
}Exportação
# Gerar spec com l5-swagger
php artisan l5-swagger:generate
# Validar spec
npx @stoplight/spectral-cli lint openapi.yaml
# Gerar cliente
npx @openapitools/openapi-generator-cli generate \
-i openapi.yaml \
-g typescript-axios \
-o ./sdk