# Openapi Spec Generation

> Genera y mantiene especificaciones OpenAPI 3.1 a partir de código, con enfoque design-first y patrones de validación de contratos de API.

Fuente: https://skillsagentes.com/skills/wshobson/agents/openapi-spec-generation
Markdown: https://skillsagentes.com/skills/wshobson/agents/openapi-spec-generation.md

Repositorio: https://github.com/wshobson/agents
Autor: wshobson
Licencia: MIT
Actualizado: hace 4 meses
Coste de contexto: 49 tok instalada, 511 tok al activarse, 6.4k tok con todos los archivos del bundle
Bundle: 3 archivos, 25 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add wshobson/agents --skill openapi-spec-generation --agent claude-code
# Cursor
npx -y skills add wshobson/agents --skill openapi-spec-generation --agent cursor
# Codex
npx -y skills add wshobson/agents --skill openapi-spec-generation --agent codex
# Gemini CLI
npx -y skills add wshobson/agents --skill openapi-spec-generation --agent gemini
# Windsurf
npx -y skills add wshobson/agents --skill openapi-spec-generation --agent windsurf
# Cline
npx -y skills add wshobson/agents --skill openapi-spec-generation --agent cline
```

## Qué hace

- Genera y mantiene especificaciones OpenAPI 3.1 a partir de código existente
- Aplica un enfoque design-first para escribir contratos de API antes de codificar
- Valida implementaciones de API contra su especificación
- Aporta plantillas y ejemplos detallados en references/details.md

## Cuándo usarla

- Crear documentación de API desde cero
- Generar specs OpenAPI a partir de código existente
- Diseñar contratos de API con enfoque design-first
- Generar SDKs de cliente a partir de specs o montar portales de documentación

## Qué la activa

- "Genera la especificación OpenAPI 3.1 para esta API REST"
- "Crea el contrato de API antes de implementar el código"
- "Valida que mi implementación cumple con el spec OpenAPI"

## Antes de instalar

- makes network requests

## Archivos

- SKILL.md — 2 KB
- references/code-first-and-tooling.md — 11 KB
- references/details.md — 12 KB

## SKILL.md

Reproducido tal cual desde wshobson/agents bajo MIT. Esta sección es el documento original y está en inglés.

# OpenAPI Spec Generation

Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.

## When to Use This Skill

- Creating API documentation from scratch
- Generating OpenAPI specs from existing code
- Designing API contracts (design-first approach)
- Validating API implementations against specs
- Generating client SDKs from specs
- Setting up API documentation portals

## Core Concepts

### 1. OpenAPI 3.1 Structure

```yaml
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. Design Approaches

| Approach         | Description                  | Best For            |
| ---------------- | ---------------------------- | ------------------- |
| **Design-First** | Write spec before code       | New APIs, contracts |
| **Code-First**   | Generate spec from code      | Existing APIs       |
| **Hybrid**       | Annotate code, generate spec | Evolving APIs       |

## Templates and detailed worked examples

Full template library and detailed worked examples live in `references/details.md`. Read that file when you need the concrete templates.

## Best Practices

### Do's

- **Use $ref** - Reuse schemas, parameters, responses
- **Add examples** - Real-world values help consumers
- **Document errors** - All possible error codes
- **Version your API** - In URL or header
- **Use semantic versioning** - For spec changes

### Don'ts

- **Don't use generic descriptions** - Be specific
- **Don't skip security** - Define all schemes
- **Don't forget nullable** - Be explicit about null
- **Don't mix styles** - Consistent naming throughout
- **Don't hardcode URLs** - Use server variables

## Dónde encaja

- Categoría: [Desarrollo de APIs](https://skillsagentes.com/categorias/desarrollo-apis.md) — Diseña, prueba y documenta APIs HTTP y GraphQL.
- Creador: [wshobson](https://skillsagentes.com/creators/wshobson.md) — 183 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Skills relacionadas

- [Rag Implementation](https://skillsagentes.com/skills/wshobson/agents/rag-implementation.md): Construye sistemas RAG (Retrieval-Augmented Generation) para aplicaciones LLM con bases de datos vectoriales y búsqueda semántica, integrando conocimiento externo.
- [Paypal Integration](https://skillsagentes.com/skills/wshobson/agents/paypal-integration.md): Integra el procesamiento de pagos de PayPal, con soporte para express checkout, suscripciones y gestión de reembolsos en flujos de comercio electrónico.
- [Nodejs Backend Patterns](https://skillsagentes.com/skills/wshobson/agents/nodejs-backend-patterns.md): Construye servicios backend de Node.js listos para producción con Express/Fastify, cubriendo middleware, manejo de errores, autenticación, bases de datos y diseño de APIs.
- [Defi Protocol Templates](https://skillsagentes.com/skills/wshobson/agents/defi-protocol-templates.md): Implementa protocolos DeFi con plantillas listas para producción de staking, AMMs, gobernanza y flash loans. Úsalo al construir aplicaciones de finanzas descentralizadas o contratos inteligentes.
- [Api Design Principles](https://skillsagentes.com/skills/wshobson/agents/api-design-principles.md): Domina los principios de diseño REST y GraphQL para construir APIs intuitivas, escalables y mantenibles que encanten a los desarrolladores.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)