1---
2name: openapi-spec-generation
3description: 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.
4---
5 
6# OpenAPI Spec Generation
7 
8Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.
9 
10## When to Use This Skill
11 
12- Creating API documentation from scratch
13- Generating OpenAPI specs from existing code
14- Designing API contracts (design-first approach)
15- Validating API implementations against specs
16- Generating client SDKs from specs
17- Setting up API documentation portals
18 
19## Core Concepts
20 
21### 1. OpenAPI 3.1 Structure
22 
23```yaml
24openapi: 3.1.0
25info:
26  title: API Title
27  version: 1.0.0
28servers:
29  - url: https://api.example.com/v1
30paths:
31  /resources:
32    get: ...
33components:
34  schemas: ...
35  securitySchemes: ...
36```
37 
38### 2. Design Approaches
39 
40| Approach         | Description                  | Best For            |
41| ---------------- | ---------------------------- | ------------------- |
42| **Design-First** | Write spec before code       | New APIs, contracts |
43| **Code-First**   | Generate spec from code      | Existing APIs       |
44| **Hybrid**       | Annotate code, generate spec | Evolving APIs       |
45 
46## Templates and detailed worked examples
47 
48Full template library and detailed worked examples live in `references/details.md`. Read that file when you need the concrete templates.
49 
50## Best Practices
51 
52### Do's
53 
54- **Use $ref** - Reuse schemas, parameters, responses
55- **Add examples** - Real-world values help consumers
56- **Document errors** - All possible error codes
57- **Version your API** - In URL or header
58- **Use semantic versioning** - For spec changes
59 
60### Don'ts
61 
62- **Don't use generic descriptions** - Be specific
63- **Don't skip security** - Define all schemes
64- **Don't forget nullable** - Be explicit about null
65- **Don't mix styles** - Consistent naming throughout
66- **Don't hardcode URLs** - Use server variables
67