Gerador de Especificação OpenAPI / Swagger

Quando Usar

Use esta habilidade quando precisar gerar especificações completas e prontas para produção do OpenAPI 3.x e Swagger 2.0 a partir de descrições em linguagem natural, código ou especificações parciais. Use esta habilidade sempre que o usuário mencionar OpenAPI, Swagger, especificação de API, documentação de API REST, esquema de API YAML/JSON, documentação de endpoint, API...

Gere especificações completas e válidas do OpenAPI 3.x ou Swagger 2.0 a partir de descrições, código ou especificações parciais.

Fluxo de Trabalho

Passo 1 — Reunir Contexto

Antes de escrever qualquer YAML/JSON, pergunte (ou infira do contexto) o seguinte:

Se o usuário fornecer código (rotas Express, FastAPI, URLs Django, controladores Spring, etc.), extraia os endpoints automaticamente — não pergunte o que o usuário já lhe disse.

Passo 2 — Construir a Especificação

Siga o guia de estrutura para a versão escolhida. Produza sempre uma especificação completa e válida — nunca deixe comentários de espaço reservado como # TODO: add schema.

Esqueleto OpenAPI 3.x

openapi: "3.1.0"
info:
  title: <API Title>
  version: "1.0.0"
  description: <Short description>
  contact:
    name: <Team or Author>
    email: <contact@example.com>
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
tags:
  - name: <Tag>
    description: <Tag description>
paths:
  /resource:
    get:
      summary: List resources
      operationId: listResources
      tags: [<Tag>]
      parameters: []
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceList"
              example:
                items: []
                total: 0
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      security:
        - BearerAuth: []
components:
  schemas: {}
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  securitySchemes: {}

Esqueleto Swagger 2.0

swagger: "2.0"
info:
  title: <API Title>
  version: "1.0.0"
  description: <Short description>
host: api.example.com
basePath: /v1
schemes: [https]
consumes: [application/json]
produces: [application/json]
tags: []
paths: {}
definitions: {}
securityDefinitions: {}

Passo 3 — Esquemas e Modelos

• Sempre use $ref para qualquer esquema usado em mais de um local.
• Inclua example ou examples em cada esquema e corpo de resposta.
• Marque os campos obrigatórios com a matriz required.
• Use nullable: true (OAS 3.0) ou x-nullable: true (Swagger 2.0) para campos opcionais anuláveis.
• Prefira palavras-chave format: int32, int64, float, date, date-time, uuid, email, uri, byte, binary.

Padrões comuns de esquema:

# Wrapper de paginação
PagedResult:
  type: object
  required: [items, total, page, pageSize]
  properties:
    items:
      type: array
      items:
        $ref: "#/components/schemas/Resource"
    total:
      type: integer
      format: int64
      example: 100
    page:
      type: integer
      format: int32
      example: 1
    pageSize:
      type: integer
      format: int32
      example: 20

# Erro padrão
Error:
  type: object
  required: [code, message]
  properties:
    code:
      type: string
      example: RESOURCE_NOT_FOUND
    message:
      type: string
      example: O recurso solicitado não foi encontrado.
    details:
      type: object
      additionalProperties: true

# Mixin de timestamps (use allOf)
Timestamps:
  type: object
  properties:
    createdAt:

…