wshobson/geração-de-especificação-openapi

O que geração-de-especificação-openapi faz?

Gere e mantenha especificações OpenAPI 3.1 a partir de código, especificações design-first e padrões de validação. Use ao criar documentação de API, gerar SDKs ou garantir conformidade com contratos de API.

Visão Geral

Esta skill permite que o agente de IA produza especificações OpenAPI 3.1 precisas a partir de diferentes fontes:

• Código existente: Analisa código-fonte (ex.: Flask, FastAPI, Express.js) para extrair definições de endpoint e schemas.
• Especificações design-first: Processa arquivos YAML/JSON existentes e os converte para o formato OpenAPI 3.1.
• Padrões de validação: Aplica regras de validação (ex.: formato de data, limites de tamanho, enumerações) para garantir que a especificação final seja completa e correta.

Plataformas Suportadas

• Claude Code
• Cursor
• Codex
• Outros agentes compatíveis com OpenAPI

Como Usar

1. Forneça o código-fonte ou a especificação existente como entrada para o agente.
2. Execute o comando para gerar a especificação OpenAPI 3.1.
3. Valide a saída com ferramentas como swagger-cli validate ou redocly lint.
4. Use a especificação gerada para documentação, geração de SDK ou testes de conformidade.

Exemplo de Uso

# Exemplo de entrada: código FastAPI
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

Saída gerada:

openapi: "3.1.0"
info:
  title: Minha API
  version: "1.0.0"
paths:
  /items/{item_id}:
    get:
      operationId: read_item
      parameters:
        - name: item_id
          in: path
          required: true
          schema:
            type: integer
        - name: q
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Resposta bem-sucedida

Validação e Conformidade

A skill aplica automaticamente as seguintes validações:

• Estrutura de caminhos (paths)
• Schemas de requisição/resposta
• Formatos de parâmetros
• Códigos de resposta HTTP
• Compatibilidade com OpenAPI 3.1

Comandos Relacionados

• openapi generate - Gera especificação a partir de código
• openapi validate - Valida especificação existente
• openapi convert - Converte entre versões OpenAPI

Licença

MIT