openapi-spec-generation
Ajuda seu agente a criar e atualizar a documentação de APIs. É útil para garantir que a documentação esteja sempre correta e para gerar código de cliente.
O que ela faz
Essa ferramenta ajuda a criar e organizar a documentação de APIs (interfaces que permitem que programas conversem entre si). Ela pode gerar essa documentação a partir do seu código ou de um design prévio.
Quando usar
- ✓Quando você precisa documentar uma API nova.
- ✓Quando você quer gerar a documentação de uma API que já existe no seu código.
- ✓Quando você precisa criar um guia para que outros programas usem sua API.
Exemplo do que pedir para a IA
“Crie a documentação OpenAPI para esta API que recebe dados de usuários.”
Quer saber mais? Abra as seções abaixo.
Como usar
O jeito mais fácil: copie a mensagem abaixo e cole no Claude, ChatGPT, Cursor ou outra IA. Ela lê a skill e segue as instruções.
Link da skill
Mensagem pronta para colar
Como funciona
A ferramenta analisa seu código ou um arquivo de design para entender como sua API funciona. Depois, ela gera um arquivo padronizado (OpenAPI 3.1) que descreve todos os detalhes da sua API.
Instalação
Jeito mais fácil: copie o link da skill e cole no Claude, ChatGPT ou Cursor pedindo para seguir as instruções.
No terminal (Claude Code, Codex, Cursor), na pasta do projeto:
npx skills add wshobson/agents --skill openapi-spec-generationOu baixe só o arquivo:
curl -L https://raw.githubusercontent.com/wshobson/agents/main/plugins/documentation-generation/skills/openapi-spec-generation/SKILL.md -o SKILL.mdConteúdo técnico (SKILL.md)
Tradução do texto original do autor no GitHub. Os comandos e códigos estão como no original.
Geração de Especificações OpenAPI
Padrões abrangentes para criar, manter e validar especificações OpenAPI 3.1 para APIs RESTful.
Quando Usar Esta Habilidade
- Criar documentação de API do zero
- Gerar especificações OpenAPI a partir de código existente
- Projetar contratos de API (abordagem "design-first")
- Validar implementações de API contra especificações
- Gerar SDKs de cliente a partir de especificações
- Configurar portais de documentação de API
Conceitos Principais
1. Estrutura do OpenAPI 3.1
openapi: 3.1.0
info:
title: API Title
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/resources:
get: ...
components:
schemas: ...
securitySchemes: ...
2. Abordagens de Design
| Abordagem | Descrição | Ideal Para |
|---|---|---|
| Design-First | Escrever a especificação antes do código | Novas APIs, contratos |
| Code-First | Gerar especificação a partir do código | APIs existentes |
| Híbrido | Anotar código, gerar especificação | APIs em evolução |
Modelos e Exemplos Detalhados
A biblioteca completa de modelos e exemplos detalhados está em references/details.md. Leia este arquivo quando precisar dos modelos concretos.
Melhores Práticas
O Que Fazer
- Use $ref - Reutilize esquemas, parâmetros, respostas
- Adicione exemplos - Valores do mundo real ajudam os consumidores
- Documente erros - Todos os códigos de erro possíveis
- Versionamento da API - Na URL ou no cabeçalho
- Use versionamento semântico - Para alterações na especificação
O Que Não Fazer
- Não use descrições genéricas - Seja específico
- Não omita a segurança - Defina todos os esquemas
- Não se esqueça de nullable - Seja explícito sobre nulo
- Não misture estilos - Nomenclatura consistente em todo o projeto
- Não codifique URLs fixas - Use variáveis de servidor
Perguntas frequentes
O que é OpenAPI?
É um formato padrão para descrever APIs, como um mapa que explica como usar um serviço online.
Qual a diferença entre 'Design-First' e 'Code-First'?
'Design-First' é criar o mapa (documentação) antes de construir a estrada (API). 'Code-First' é criar a estrada e depois gerar o mapa a partir dela.
Por que usar '$ref'?
É como criar um atalho para não repetir informações. Se você descreve um tipo de dado em um lugar, pode usar '$ref' para reutilizar essa descrição em outros lugares.
Detalhes
Descrição original do autor
Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance.
repo: wshobson/agents
Popularidade
- Estrelas no GitHub
- 41 mil
- Posição no ranking
- #4857
- Licença
- MIT
- Atualizada em
- 15/10/2026
Comentários
- …
Mais skills deste repositório
screen-reader-testing
Faz seu agente testar sites usando leitores de tela para garantir que sejam acessíveis.
wshobson/agents
wcag-audit-patterns
Ajuda seu agente a auditar sites para acessibilidade e corrigir problemas de acordo com as diretrizes WCAG.
wshobson/agents
multi-reviewer-patterns
Faz seu agente coordenar revisões de código paralelas, deduplicando achados e consolidando relatórios.
wshobson/agents
parallel-debugging
Permite ao agente depurar problemas complexos com investigações paralelas e análise de causa raiz.
wshobson/agents
Skills parecidas
api-connector-builder
Faz seu agente construir novas conexões com APIs seguindo o padrão já existente. Use quando precisar adicionar mais uma integração sem criar um novo jeito de fazer.
affaan-m/ECC
api-design
Ajuda seu agente a projetar APIs REST seguindo as melhores práticas. É útil para definir como as APIs se comunicam, como os erros são mostrados e como organizar os dados.
affaan-m/ECC
backend-patterns
Ajuda seu agente com padrões de arquitetura do lado do servidor e otimização de banco de dados. É útil para construir ou revisar o código que roda no servidor.
affaan-m/ECC