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
47 
48### Template 1: Complete API Specification
49 
50```yaml
51openapi: 3.1.0
52info:
53  title: User Management API
54  description: |
55    API for managing users and their profiles.
56 
57    ## Authentication
58    All endpoints require Bearer token authentication.
59 
60    ## Rate Limiting
61    - 1000 requests per minute for standard tier
62    - 10000 requests per minute for enterprise tier
63  version: 2.0.0
64  contact:
65    name: API Support
66    email: [email protected]
67    url: https://docs.example.com
68  license:
69    name: MIT
70    url: https://opensource.org/licenses/MIT
71 
72servers:
73  - url: https://api.example.com/v2
74    description: Production
75  - url: https://staging-api.example.com/v2
76    description: Staging
77  - url: http://localhost:3000/v2
78    description: Local development
79 
80tags:
81  - name: Users
82    description: User management operations
83  - name: Profiles
84    description: User profile operations
85  - name: Admin
86    description: Administrative operations
87 
88paths:
89  /users:
90    get:
91      operationId: listUsers
92      summary: List all users
93      description: Returns a paginated list of users with optional filtering.
94      tags:
95        - Users
96      parameters:
97        - $ref: "#/components/parameters/PageParam"
98        - $ref: "#/components/parameters/LimitParam"
99        - name: status
100          in: query
101          description: Filter by user status
102          schema:
103            $ref: "#/components/schemas/UserStatus"
104        - name: search
105          in: query
106          description: Search by name or email
107          schema:
108            type: string
109            minLength: 2
110            maxLength: 100
111      responses:
112        "200":
113          description: Successful response
114          content:
115            application/json:
116              schema:
117                $ref: "#/components/schemas/UserListResponse"
118              examples:
119                default:
120                  $ref: "#/components/examples/UserListExample"
121        "400":
122          $ref: "#/components/responses/BadRequest"
123        "401":
124          $ref: "#/components/responses/Unauthorized"
125        "429":
126          $ref: "#/components/responses/RateLimited"
127      security:
128        - bearerAuth: []
129 
130    post:
131      operationId: createUser
132      summary: Create a new user
133      description: Creates a new user account and sends welcome email.
134      tags:
135        - Users
136      requestBody:
137        required: true
138        content:
139          application/json:
140            schema:
141              $ref: "#/components/schemas/CreateUserRequest"
142            examples:
143              standard:
144                summary: Standard user
145                value:
146                  email: [email protected]
147                  name: John Doe
148                  role: user
149              admin:
150                summary: Admin user
151                value:
152                  email: [email protected]
153                  name: Admin User
154                  role: admin
155      responses:
156        "201":
157          description: User created successfully
158          content:
159            application/json:
160              schema:
161                $ref: "#/components/schemas/User"
162          headers:
163            Location:
164              description: URL of created user
165              schema:
166                type: string
167                format: uri
168        "400":
169          $ref: "#/components/responses/BadRequest"
170        "409":
171          description: Email already exists
172          content:
173            application/json:
174              schema:
175                $ref: "#/components/schemas/Error"
176      security:
177        - bearerAuth: []
178 
179  /users/{userId}:
180    parameters:
181      - $ref: "#/components/parameters/UserIdParam"
182 
183    get:
184      operationId: getUser
185      summary: Get user by ID
186      tags:
187        - Users
188      responses:
189        "200":
190          description: Successful response
191          content:
192            application/json:
193              schema:
194                $ref: "#/components/schemas/User"
195        "404":
196          $ref: "#/components/responses/NotFound"
197      security:
198        - bearerAuth: []
199 
200    patch:
201      operationId: updateUser
202      summary: Update user
203      tags:
204        - Users
205      requestBody:
206        required: true
207        content:
208          application/json:
209            schema:
210              $ref: "#/components/schemas/UpdateUserRequest"
211      responses:
212        "200":
213          description: User updated
214          content:
215            application/json:
216              schema:
217                $ref: "#/components/schemas/User"
218        "400":
219          $ref: "#/components/responses/BadRequest"
220        "404":
221          $ref: "#/components/responses/NotFound"
222      security:
223        - bearerAuth: []
224 
225    delete:
226      operationId: deleteUser
227      summary: Delete user
228      tags:
229        - Users
230        - Admin
231      responses:
232        "204":
233          description: User deleted
234        "404":
235          $ref: "#/components/responses/NotFound"
236      security:
237        - bearerAuth: []
238        - apiKey: []
239 
240components:
241  schemas:
242    User:
243      type: object
244      required:
245        - id
246        - email
247        - name
248        - status
249        - createdAt
250      properties:
251        id:
252          type: string
253          format: uuid
254          readOnly: true
255          description: Unique user identifier
256        email:
257          type: string
258          format: email
259          description: User email address
260        name:
261          type: string
262          minLength: 1
263          maxLength: 100
264          description: User display name
265        status:
266          $ref: "#/components/schemas/UserStatus"
267        role:
268          type: string
269          enum: [user, moderator, admin]
270          default: user
271        avatar:
272          type: string
273          format: uri
274          nullable: true
275        metadata:
276          type: object
277          additionalProperties: true
278          description: Custom metadata
279        createdAt:
280          type: string
281          format: date-time
282          readOnly: true
283        updatedAt:
284          type: string
285          format: date-time
286          readOnly: true
287 
288    UserStatus:
289      type: string
290      enum: [active, inactive, suspended, pending]
291      description: User account status
292 
293    CreateUserRequest:
294      type: object
295      required:
296        - email
297        - name
298      properties:
299        email:
300          type: string
301          format: email
302        name:
303          type: string
304          minLength: 1
305          maxLength: 100
306        role:
307          type: string
308          enum: [user, moderator, admin]
309          default: user
310        metadata:
311          type: object
312          additionalProperties: true
313 
314    UpdateUserRequest:
315      type: object
316      minProperties: 1
317      properties:
318        name:
319          type: string
320          minLength: 1
321          maxLength: 100
322        status:
323          $ref: "#/components/schemas/UserStatus"
324        role:
325          type: string
326          enum: [user, moderator, admin]
327        metadata:
328          type: object
329          additionalProperties: true
330 
331    UserListResponse:
332      type: object
333      required:
334        - data
335        - pagination
336      properties:
337        data:
338          type: array
339          items:
340            $ref: "#/components/schemas/User"
341        pagination:
342          $ref: "#/components/schemas/Pagination"
343 
344    Pagination:
345      type: object
346      required:
347        - page
348        - limit
349        - total
350        - totalPages
351      properties:
352        page:
353          type: integer
354          minimum: 1
355        limit:
356          type: integer
357          minimum: 1
358          maximum: 100
359        total:
360          type: integer
361          minimum: 0
362        totalPages:
363          type: integer
364          minimum: 0
365        hasNext:
366          type: boolean
367        hasPrev:
368          type: boolean
369 
370    Error:
371      type: object
372      required:
373        - code
374        - message
375      properties:
376        code:
377          type: string
378          description: Error code for programmatic handling
379        message:
380          type: string
381          description: Human-readable error message
382        details:
383          type: array
384          items:
385            type: object
386            properties:
387              field:
388                type: string
389              message:
390                type: string
391        requestId:
392          type: string
393          description: Request ID for support
394 
395  parameters:
396    UserIdParam:
397      name: userId
398      in: path
399      required: true
400      description: User ID
401      schema:
402        type: string
403        format: uuid
404 
405    PageParam:
406      name: page
407      in: query
408      description: Page number (1-based)
409      schema:
410        type: integer
411        minimum: 1
412        default: 1
413 
414    LimitParam:
415      name: limit
416      in: query
417      description: Items per page
418      schema:
419        type: integer
420        minimum: 1
421        maximum: 100
422        default: 20
423 
424  responses:
425    BadRequest:
426      description: Invalid request
427      content:
428        application/json:
429          schema:
430            $ref: "#/components/schemas/Error"
431          example:
432            code: VALIDATION_ERROR
433            message: Invalid request parameters
434            details:
435              - field: email
436                message: Must be a valid email address
437 
438    Unauthorized:
439      description: Authentication required
440      content:
441        application/json:
442          schema:
443            $ref: "#/components/schemas/Error"
444          example:
445            code: UNAUTHORIZED
446            message: Authentication required
447 
448    NotFound:
449      description: Resource not found
450      content:
451        application/json:
452          schema:
453            $ref: "#/components/schemas/Error"
454          example:
455            code: NOT_FOUND
456            message: User not found
457 
458    RateLimited:
459      description: Too many requests
460      content:
461        application/json:
462          schema:
463            $ref: "#/components/schemas/Error"
464      headers:
465        Retry-After:
466          description: Seconds until rate limit resets
467          schema:
468            type: integer
469        X-RateLimit-Limit:
470          description: Request limit per window
471          schema:
472            type: integer
473        X-RateLimit-Remaining:
474          description: Remaining requests in window
475          schema:
476            type: integer
477 
478  examples:
479    UserListExample:
480      value:
481        data:
482          - id: "550e8400-e29b-41d4-a716-446655440000"
483            email: "[email protected]"
484            name: "John Doe"
485            status: "active"
486            role: "user"
487            createdAt: "2024-01-15T10:30:00Z"
488        pagination:
489          page: 1
490          limit: 20
491          total: 1
492          totalPages: 1
493          hasNext: false
494          hasPrev: false
495 
496  securitySchemes:
497    bearerAuth:
498      type: http
499      scheme: bearer
500      bearerFormat: JWT
501      description: JWT token from /auth/login
502 
503    apiKey:
504      type: apiKey
505      in: header
506      name: X-API-Key
507      description: API key for service-to-service calls
508 
509security:
510  - bearerAuth: []
511```
512 
513For advanced code-first generation patterns and tooling, see [references/code-first-and-tooling.md](references/code-first-and-tooling.md):
514 
515- **Template 2: Python/FastAPI** — Pydantic models with `Field` validation, enum types, full CRUD endpoints with `response_model` and `status_code`, exporting the spec as JSON
516- **Template 3: TypeScript/tsoa** — Decorator-based controllers (`@Route`, `@Get`, `@Security`, `@Example`, `@Response`) that generate OpenAPI from TypeScript types
517- **Template 4: Validation & Linting** — Spectral ruleset (`.spectral.yaml`) with custom rules for operationId, security, naming conventions; Redocly config with MIME type enforcement and code sample generation
518- **SDK Generation** — `openapi-generator-cli` for TypeScript (fetch), Python, and Go clients
519 
520## Best Practices
521 
522### Do's
523 
524- **Use $ref** - Reuse schemas, parameters, responses
525- **Add examples** - Real-world values help consumers
526- **Document errors** - All possible error codes
527- **Version your API** - In URL or header
528- **Use semantic versioning** - For spec changes
529 
530### Don'ts
531 
532- **Don't use generic descriptions** - Be specific
533- **Don't skip security** - Define all schemes
534- **Don't forget nullable** - Be explicit about null
535- **Don't mix styles** - Consistent naming throughout
536- **Don't hardcode URLs** - Use server variables
537