Documentação com OpenAPI

OpenAPI Specification

OpenAPI (antigo Swagger) é o padrão para documentar REST APIs.

openapi: 3.1.0
info:
  title: Pet Store API
  description: API para gerenciamento de pets
  version: 1.0.0
  contact:
    name: Suporte
    email: [email protected]
servers:
  - url: https://api.petstore.com/v1
    description: Produção
  - url: https://staging.api.petstore.com/v1
    description: Staging
security:
  - bearerAuth: []
paths:
  /pets:
    get:
      summary: Lista todos os pets
      operationId: listPets
      tags: [Pets]
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            maximum: 100
            default: 20
          description: Máximo de itens
      responses:
        '200':
          description: Lista de pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Pet:
      type: object
      required: [name]
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          example: "Rex"
        status:
          type: string
          enum: [available, pending, sold]

OpenAPI com JSON

{
  "openapi": "3.1.0",
  "info": {
    "title": "Users API",
    "version": "2.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "operationId": "getUsers",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserList"
                }
              }
            }
          }
        }
      }
    }
  }
}

Code Generation

# Gerar servidor Java/Spring
openapi-generator generate -i api.yaml -g spring -o ./server

# Gerar cliente TypeScript
openapi-generator generate -i api.yaml -g typescript-axios -o ./client

# Gerar documentação HTML
redoc-cli build api.yaml -o docs.html

Ferramentas

Ferramenta	Uso
Swagger Editor	Editor online do spec
Swagger UI	Documentação interativa
ReDoc	Documentação elegante
Stoplight	Plataforma completa de API design
Postman	Testes + collections importáveis
Insomnia	Cliente REST com suporte OpenAPI
openapi-generator	Geração de código client/server

Lab: API com OpenAPI + Postman

openapi: 3.0.0
info:
  title: Minha API
  version: 1.0.0
paths:
  /pets:
    post:
      summary: Create a pet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePet'
      responses:
        '201':
          $ref: '#/components/responses/PetCreated'

components:
  schemas:
    CreatePet:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 100
        tag:
          type: string
    Pet:
      allOf:
        - $ref: '#/components/schemas/CreatePet'
        - type: object
          properties:
            id:
              type: integer
            createdAt:
              type: string
              format: date-time
  responses:
    PetCreated:
      description: Pet created
      headers:
        Location:
          schema:
            type: string
            format: uri
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Pet'
    BadRequest:
      description: Invalid input
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
              message:
                type: string

# Importar no Postman: File > Import > api.yaml
# Testar endpoints

# Validar spec
npx @apidevtools/swagger-cli validate api.yaml

OpenAPI é o contrato da sua API. Documente antes de codificar. Gere cliente/servidor do spec. Ferramentas como Swagger UI e Postman consomem o spec para testes interativos.