OpenAPI Spec Writer

Overview

Expert in writing OpenAPI 3.0/3.1 specifications for REST APIs. Specializes in schema design, documentation best practices, API-first development, and tooling integration. Generates comprehensive API documentation that serves as both documentation and contract.

When to Use

• Creating OpenAPI specifications for new APIs
• Documenting existing REST APIs
• Designing API contracts before implementation
• Generating client SDKs from specs
• Setting up interactive API documentation (Swagger UI, Redoc)
• Validating API responses against schemas
• Migrating from OpenAPI 2.0 (Swagger) to 3.x

Capabilities

Specification Writing

• OpenAPI 3.0 and 3.1 syntax
• Path and operation definitions
• Request/response schemas
• Authentication schemes
• Server configurations

Schema Design

• JSON Schema with OpenAPI extensions
• Reusable component schemas
• Discriminators for polymorphism
• oneOf, anyOf, allOf composition
• Nullable types and defaults

Documentation Quality

• Meaningful descriptions and examples
• Markdown in descriptions
• Request/response examples
• Error response documentation
• Deprecation notices

Tooling Integration

• Swagger UI configuration
• Redoc customization
• Spectral linting rules
• SDK generation setup
• Mock server configuration

Dependencies

Works well with:

• api-architect - API design patterns
• rest-api-design - RESTful conventions
• typescript-pro - Generated client types
• github-actions-pipeline-builder - CI validation

Examples

Complete OpenAPI 3.1 Spec

yaml
1openapi: 3.1.0
2info:
3  title: Task Management API
4  description: |
5    RESTful API for managing tasks and projects.
6
7    ## Authentication
8    All endpoints require a Bearer token in the Authorization header.
9
10    ## Rate Limiting
11    - 1000 requests per hour per API key
12    - Rate limit headers included in all responses
13  version: 1.0.0
14  contact:
15    name: API Support
16    email: api@example.com
17    url: https://docs.example.com
18  license:
19    name: MIT
20    url: https://opensource.org/licenses/MIT
21
22servers:
23  - url: https://api.example.com/v1
24    description: Production server
25  - url: https://staging-api.example.com/v1
26    description: Staging server
27  - url: http://localhost:3000/v1
28    description: Local development
29
30tags:
31  - name: Tasks
32    description: Task management operations
33  - name: Projects
34    description: Project management operations
35
36paths:
37  /tasks:
38    get:
39      operationId: listTasks
40      summary: List all tasks
41      description: Returns a paginated list of tasks with optional filtering.
42      tags:
43        - Tasks
44      parameters:
45        - $ref: '#/components/parameters/PageParam'
46        - $ref: '#/components/parameters/LimitParam'
47        - name: status
48          in: query
49          description: Filter by task status
50          schema:
51            $ref: '#/components/schemas/TaskStatus'
52        - name: project_id
53          in: query
54          description: Filter by project ID
55          schema:
56            type: string
57            format: uuid
58      responses:
59        '200':
60          description: Successful response
61          content:
62            application/json:
63              schema:
64                $ref: '#/components/schemas/TaskListResponse'
65              examples:
66                default:
67                  $ref: '#/components/examples/TaskListExample'
68          headers:
69            X-Total-Count:
70              schema:
71                type: integer
72              description: Total number of tasks matching the query
73        '400':
74          $ref: '#/components/responses/BadRequest'
75        '401':
76          $ref: '#/components/responses/Unauthorized'
77
78    post:
79      operationId: createTask
80      summary: Create a new task
81      description: Creates a new task and returns the created resource.
82      tags:
83        - Tasks
84      requestBody:
85        required: true
86        content:
87          application/json:
88            schema:
89              $ref: '#/components/schemas/CreateTaskRequest'
90            examples:
91              minimal:
92                summary: Minimal task
93                value:
94                  title: "Complete documentation"
95              full:
96                summary: Full task with all fields
97                value:
98                  title: "Complete documentation"
99                  description: "Write API docs for v1.0"
100                  project_id: "550e8400-e29b-41d4-a716-446655440000"
101                  due_date: "2024-12-31"
102                  priority: "high"
103      responses:
104        '201':
105          description: Task created successfully
106          content:
107            application/json:
108              schema:
109                $ref: '#/components/schemas/Task'
110          headers:
111            Location:
112              schema:
113                type: string
114                format: uri
115              description: URL of the created resource
116        '400':
117          $ref: '#/components/responses/BadRequest'
118        '401':
119          $ref: '#/components/responses/Unauthorized'
120        '422':
121          $ref: '#/components/responses/ValidationError'
122
123  /tasks/{taskId}:
124    parameters:
125      - $ref: '#/components/parameters/TaskIdParam'
126
127    get:
128      operationId: getTask
129      summary: Get a task by ID
130      tags:
131        - Tasks
132      responses:
133        '200':
134          description: Successful response
135          content:
136            application/json:
137              schema:
138                $ref: '#/components/schemas/Task'
139        '404':
140          $ref: '#/components/responses/NotFound'
141
142    patch:
143      operationId: updateTask
144      summary: Update a task
145      description: Partially updates a task. Only provided fields are updated.
146      tags:
147        - Tasks
148      requestBody:
149        required: true
150        content:
151          application/json:
152            schema:
153              $ref: '#/components/schemas/UpdateTaskRequest'
154      responses:
155        '200':
156          description: Task updated successfully
157          content:
158            application/json:
159              schema:
160                $ref: '#/components/schemas/Task'
161        '404':
162          $ref: '#/components/responses/NotFound'
163        '422':
164          $ref: '#/components/responses/ValidationError'
165
166    delete:
167      operationId: deleteTask
168      summary: Delete a task
169      tags:
170        - Tasks
171      responses:
172        '204':
173          description: Task deleted successfully
174        '404':
175          $ref: '#/components/responses/NotFound'
176
177components:
178  securitySchemes:
179    bearerAuth:
180      type: http
181      scheme: bearer
182      bearerFormat: JWT
183      description: JWT token obtained from /auth/login
184
185  parameters:
186    TaskIdParam:
187      name: taskId
188      in: path
189      required: true
190      description: Unique task identifier
191      schema:
192        type: string
193        format: uuid
194      example: "550e8400-e29b-41d4-a716-446655440000"
195
196    PageParam:
197      name: page
198      in: query
199      description: Page number for pagination (1-indexed)
200      schema:
201        type: integer
202        minimum: 1
203        default: 1
204
205    LimitParam:
206      name: limit
207      in: query
208      description: Number of items per page
209      schema:
210        type: integer
211        minimum: 1
212        maximum: 100
213        default: 20
214
215  schemas:
216    Task:
217      type: object
218      required:
219        - id
220        - title
221        - status
222        - created_at
223        - updated_at
224      properties:
225        id:
226          type: string
227          format: uuid
228          description: Unique identifier
229          readOnly: true
230        title:
231          type: string
232          minLength: 1
233          maxLength: 200
234          description: Task title
235        description:
236          type: string
237          maxLength: 5000
238          description: Detailed task description (supports Markdown)
239        status:
240          $ref: '#/components/schemas/TaskStatus'
241        priority:
242          $ref: '#/components/schemas/Priority'
243        project_id:
244          type: string
245          format: uuid
246          description: Associated project ID
247        due_date:
248          type: string
249          format: date
250          description: Due date (ISO 8601)
251        created_at:
252          type: string
253          format: date-time
254          readOnly: true
255        updated_at:
256          type: string
257          format: date-time
258          readOnly: true
259
260    TaskStatus:
261      type: string
262      enum:
263        - pending
264        - in_progress
265        - completed
266        - cancelled
267      description: Current task status
268      default: pending
269
270    Priority:
271      type: string
272      enum:
273        - low
274        - medium
275        - high
276        - urgent
277      default: medium
278
279    CreateTaskRequest:
280      type: object
281      required:
282        - title
283      properties:
284        title:
285          type: string
286          minLength: 1
287          maxLength: 200
288        description:
289          type: string
290          maxLength: 5000
291        project_id:
292          type: string
293          format: uuid
294        due_date:
295          type: string
296          format: date
297        priority:
298          $ref: '#/components/schemas/Priority'
299
300    UpdateTaskRequest:
301      type: object
302      minProperties: 1
303      properties:
304        title:
305          type: string
306          minLength: 1
307          maxLength: 200
308        description:
309          type: string
310          maxLength: 5000
311        status:
312          $ref: '#/components/schemas/TaskStatus'
313        priority:
314          $ref: '#/components/schemas/Priority'
315        due_date:
316          type: string
317          format: date
318
319    TaskListResponse:
320      type: object
321      required:
322        - data
323        - pagination
324      properties:
325        data:
326          type: array
327          items:
328            $ref: '#/components/schemas/Task'
329        pagination:
330          $ref: '#/components/schemas/Pagination'
331
332    Pagination:
333      type: object
334      required:
335        - page
336        - limit
337        - total
338        - total_pages
339      properties:
340        page:
341          type: integer
342        limit:
343          type: integer
344        total:
345          type: integer
346        total_pages:
347          type: integer
348        has_next:
349          type: boolean
350        has_prev:
351          type: boolean
352
353    Error:
354      type: object
355      required:
356        - code
357        - message
358      properties:
359        code:
360          type: string
361          description: Machine-readable error code
362        message:
363          type: string
364          description: Human-readable error message
365        details:
366          type: object
367          additionalProperties: true
368          description: Additional error details
369
370    ValidationError:
371      allOf:
372        - $ref: '#/components/schemas/Error'
373        - type: object
374          properties:
375            errors:
376              type: array
377              items:
378                type: object
379                properties:
380                  field:
381                    type: string
382                  message:
383                    type: string
384
385  responses:
386    BadRequest:
387      description: Bad request - invalid parameters
388      content:
389        application/json:
390          schema:
391            $ref: '#/components/schemas/Error'
392          example:
393            code: "BAD_REQUEST"
394            message: "Invalid query parameters"
395
396    Unauthorized:
397      description: Authentication required
398      content:
399        application/json:
400          schema:
401            $ref: '#/components/schemas/Error'
402          example:
403            code: "UNAUTHORIZED"
404            message: "Invalid or expired token"
405
406    NotFound:
407      description: Resource not found
408      content:
409        application/json:
410          schema:
411            $ref: '#/components/schemas/Error'
412          example:
413            code: "NOT_FOUND"
414            message: "Task not found"
415
416    ValidationError:
417      description: Validation failed
418      content:
419        application/json:
420          schema:
421            $ref: '#/components/schemas/ValidationError'
422          example:
423            code: "VALIDATION_ERROR"
424            message: "Request validation failed"
425            errors:
426              - field: "title"
427                message: "Title is required"
428
429  examples:
430    TaskListExample:
431      value:
432        data:
433          - id: "550e8400-e29b-41d4-a716-446655440000"
434            title: "Complete documentation"
435            status: "in_progress"
436            priority: "high"
437            created_at: "2024-01-15T10:30:00Z"
438            updated_at: "2024-01-15T10:30:00Z"
439        pagination:
440          page: 1
441          limit: 20
442          total: 42
443          total_pages: 3
444          has_next: true
445          has_prev: false
446
447security:
448  - bearerAuth: []

Polymorphic Schemas (Discriminator)

yaml
1components:
2  schemas:
3    Notification:
4      type: object
5      required:
6        - id
7        - type
8        - created_at
9      discriminator:
10        propertyName: type
11        mapping:
12          email: '#/components/schemas/EmailNotification'
13          sms: '#/components/schemas/SmsNotification'
14          push: '#/components/schemas/PushNotification'
15      properties:
16        id:
17          type: string
18          format: uuid
19        type:
20          type: string
21          enum: [email, sms, push]
22        created_at:
23          type: string
24          format: date-time
25
26    EmailNotification:
27      allOf:
28        - $ref: '#/components/schemas/Notification'
29        - type: object
30          required:
31            - to
32            - subject
33          properties:
34            to:
35              type: string
36              format: email
37            subject:
38              type: string
39            body:
40              type: string
41
42    SmsNotification:
43      allOf:
44        - $ref: '#/components/schemas/Notification'
45        - type: object
46          required:
47            - phone_number
48            - message
49          properties:
50            phone_number:
51              type: string
52              pattern: '^\+[1-9]\d{1,14}$'
53            message:
54              type: string
55              maxLength: 160

Spectral Linting Rules

yaml
1# .spectral.yaml
2extends: ["spectral:oas"]
3
4rules:
5  # Enforce operation IDs
6  operation-operationId: error
7
8  # Require descriptions
9  operation-description: error
10  oas3-schema-description: warn
11
12  # Naming conventions
13  path-casing:
14    given: "$.paths[*]~"
15    then:
16      function: casing
17      functionOptions:
18        type: kebab
19
20  # Security requirements
21  operation-security-defined: error
22
23  # Response codes
24  operation-success-response: error
25
26  # Custom: require examples
27  require-examples:
28    message: "Responses should have examples"
29    given: "$.paths.*.*.responses.*.content.*.schema"
30    then:
31      field: example
32      function: truthy

Best Practices

1. Use components - Extract reusable schemas, parameters, responses
2. Provide examples - Real-world examples for every schema
3. Meaningful descriptions - Markdown-formatted, explain business context
4. Consistent naming - kebab-case paths, camelCase properties
5. Version your API - Include version in URL or header
6. Document errors - Define all error responses with examples
7. Use operationId - Unique, descriptive IDs for SDK generation
8. Validate with linting - Use Spectral to enforce standards
9. Keep spec in sync - Automate validation in CI

Common Pitfalls

• Missing required fields - Forgetting to mark fields as required
• Inconsistent naming - Mixing snake_case and camelCase
• Generic descriptions - "Returns data" instead of specific details
• No examples - Makes spec hard to understand
• Outdated spec - Spec doesn't match implementation
• Overusing anyOf - Makes schemas hard to understand
• Missing error responses - Only documenting happy path
• No pagination - List endpoints without pagination info