---
name: generacion-especificaciones-openapi
description: Genera y mantiene especificaciones OpenAPI 3.1 para APIs REST a partir de código existente o mediante enfoque design-first. Facilita la documentación de APIs, la generación de SDKs y la validación de contratos de integración.
license: MIT
metadata:
  id: 1f112ee5
  slug: generacion-especificaciones-openapi
  titulo: "Generación de Especificaciones OpenAPI"
  servicio: Web
  categoria_recurso: Web-Desarrollo
  tipo: generacion
  nivel: intermedio
  idioma: es
  idioma_original: en
  acceso: gratis
  precio_eur: 0
  plataformas: [Claude Code, Codex CLI, Cursor, OpenCode, Gemini CLI]
  dependencias: []
  licencia: { spdx: MIT, redistribuible: true, uso_comercial: true }
  fuente:
    repo: wshobson/agents
    url: https://github.com/wshobson/agents/tree/main/plugins/documentation-generation/skills/openapi-spec-generation
    commit: cc37bfd
    autor: wshobson
    nombre_original: openapi-spec-generation
    duplicados_en: []
  seguridad: { veredicto: seguro, riesgo: bajo, escaneado: "2026-06-14", motor: "grep-estatico+auditor-llm" }
  ficha:
    que_hace: "Genera especificaciones OpenAPI 3.1 completas para documentar y validar APIs REST."
    como_lo_hace: "Aplica patrones de diseño design-first, code-first e híbrido con plantillas YAML y buenas prácticas de seguridad, versionado y reutilización de esquemas."
  content_hash: "1f112ee524de130632e738e330c4fdbc6be2a4848b0abb324833321deb1cacc4"
  version: 1.0.0
---

# 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