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