OpenAPI Generator

API Metadata

OpenAPI Version

API Title

A short, descriptive title for your API.

API Version

Semantic versioning of your API (e.g., 1.0.0).

Description

A detailed description of what your API does.

Server & Security

Server URL

The base URL for your production API server.

Authentication Scheme

Schema Content

Include Examples- Generate mock examples in schema definitions.

Include Error Models- Generate standard error response schemas (e.g., 404, 422).

openapi.yaml

1openapi: 3.0.3
2info:
3  title: My Production API
4  version: 1.0.0
5  description: Enterprise API providing access to core platform features.
6  contact:
7    name: API Support
8    email: api-support@example.com
9  license:
10    name: MIT
11    url: https://opensource.org/licenses/MIT
12servers:
13  - url: https://api.example.com/v1
14    description: Production Server
15  - url: http://localhost:3000api.example.com
16    description: Local Development
17paths:
18  /users:
19    get:
20      summary: List users
21      description: Returns a paginated list of users. Supports filtering and sorting.
22      operationId: listUsers
23      tags:
24        - Users
25      parameters:
26        - name: page
27          in: query
28          description: 'Page number (default: 1)'
29          schema:
30            type: integer
31            default: 1
32            minimum: 1
33        - name: limit
34          in: query
35          description: 'Items per page (default: 20, max: 100)'
36          schema:
37            type: integer
38            default: 20
39            minimum: 1
40            maximum: 100
41        - name: sort
42          in: query
43          description: Sort field
44          schema:
45            type: string
46            enum:
47              - createdAt
48              - name
49              - email
50            default: createdAt
51        - name: order
52          in: query
53          description: Sort order
54          schema:
55            type: string
56            enum:
57              - asc
58              - desc
59            default: desc
60        - name: search
61          in: query
62          description: Search by name or email
63          schema:
64            type: string
65      responses:
66        '200':
67          description: A paginated list of users
68          content:
69            application/json:
70              schema:
71                $ref: '#/components/schemas/PaginatedUsers'
72              example:
73                data:
74                  - id: 123e4567-e89b-12d3-a456-426614174000
75                    name: Jane Doe
76                    email: jane@example.com
77                    role: user
78                    createdAt: '2024-01-15T10:30:00Z'
79                    updatedAt: '2024-01-15T10:30:00Z'
80                meta:
81                  total: 1
82                  page: 1
83                  limit: 20
84                  totalPages: 1
85        '401':
86          $ref: '#/components/responses/Unauthorized'
87        '429':
88          description: Rate limit exceeded
89          content:
90            application/json:
91              schema:
92                $ref: '#/components/schemas/ErrorResponse'
93        '500':
94          description: Internal server error
95    post:
96      summary: Create a new user
97      description: Creates a new user with the provided data. Returns the created user.
98      operationId: createUser
99      tags:
100        - Users
101      requestBody:
102        required: true
103        content:
104          application/json:
105            schema:
106              $ref: '#/components/schemas/CreateUserInput'
107            example:
108              name: Jane Doe
109              email: jane@example.com
110              role: user
111      responses:
112        '201':
113          description: User created successfully
114          content:
115            application/json:
116              schema:
117                type: object
118                properties:
119                  status:
120                    type: string
121                    example: success
122                  data:
123                    $ref: '#/components/schemas/User'
124        '400':
125          description: Bad request - Invalid input
126        '401':
127          description: Unauthorized - Invalid or missing authentication
128        '409':
129          description: Conflict - User with this email already exists
130        '422':
131          description: Validation failed
132        '429':
133          description: Rate limit exceeded
134        '500':
135          description: Internal server error
136  /users/{id}:
137    get:
138      summary: Get a user by ID
139      description: Returns a single user by their unique identifier.
140      operationId: getUser
141      tags:
142        - Users
143      parameters:
144        - name: id
145          in: path
146          required: true
147          description: The user's unique identifier
148          schema:
149            type: string
150            format: uuid
151      responses:
152        '200':
153          description: User found
154          content:
155            application/json:
156              schema:
157                type: object
158                properties:
159                  status:
160                    type: string
161                  data:
162                    $ref: '#/components/schemas/User'
163        '401':
164          description: Unauthorized
165        '404':
166          description: User not found
167        '429':
168          description: Rate limit exceeded
169        '500':
170          description: Internal server error
171    put:
172      summary: Replace a user
173      description: Replaces all fields of an existing user. All required fields must be provided.
174      operationId: replaceUser
175      tags:
176        - Users
177      parameters:
178        - name: id
179          in: path
180          required: true
181          schema:
182            type: string
183            format: uuid
184      requestBody:
185        required: true
186        content:
187          application/json:
188            schema:
189              $ref: '#/components/schemas/CreateUserInput'
190      responses:
191        '200':
192          description: User replaced successfully
193          content:
194            application/json:
195              schema:
196                type: object
197                properties:
198                  status:
199                    type: string
200                  data:
201                    $ref: '#/components/schemas/User'
202        '400':
203          description: Bad request
204        '401':
205          description: Unauthorized
206        '404':
207          description: Not found
208        '422':
209          description: Validation failed
210        '429':
211          description: Rate limit exceeded
212        '500':
213          description: Internal server error
214    patch:
215      summary: Update a user
216      description: Partially updates an existing user. Only provided fields will be updated.
217      operationId: updateUser
218      tags:
219        - Users
220      parameters:
221        - name: id
222          in: path
223          required: true
224          schema:
225            type: string
226            format: uuid
227      requestBody:
228        required: true
229        content:
230          application/json:
231            schema:
232              $ref: '#/components/schemas/UpdateUserInput'
233      responses:
234        '200':
235          description: User updated successfully
236          content:
237            application/json:
238              schema:
239                type: object
240                properties:
241                  status:
242                    type: string
243                  data:
244                    $ref: '#/components/schemas/User'
245        '400':
246          description: Bad request
247        '401':
248          description: Unauthorized
249        '404':
250          description: Not found
251        '422':
252          description: Validation failed
253        '429':
254          description: Rate limit exceeded
255        '500':
256          description: Internal server error
257    delete:
258      summary: Delete a user
259      description: Permanently deletes a user by their unique identifier.
260      operationId: deleteUser
261      tags:
262        - Users
263      parameters:
264        - name: id
265          in: path
266          required: true
267          schema:
268            type: string
269            format: uuid
270      responses:
271        '204':
272          description: User deleted successfully
273        '401':
274          description: Unauthorized
275        '404':
276          description: Not found
277        '429':
278          description: Rate limit exceeded
279        '500':
280          description: Internal server error
281components:
282  schemas:
283    User:
284      type: object
285      required:
286        - id
287        - name
288        - email
289        - createdAt
290      properties:
291        id:
292          type: string
293          format: uuid
294          description: Unique identifier for the user
295        name:
296          type: string
297          minLength: 1
298          maxLength: 255
299          description: Full name of the user
300        email:
301          type: string
302          format: email
303          description: Email address of the user
304        role:
305          type: string
306          enum:
307            - admin
308            - user
309            - viewer
310          default: user
311          description: Role assigned to the user
312        createdAt:
313          type: string
314          format: date-time
315          description: ISO 8601 timestamp when the user was created
316        updatedAt:
317          type: string
318          format: date-time
319          description: ISO 8601 timestamp when the user was last updated
320      example:
321        id: 123e4567-e89b-12d3-a456-426614174000
322        name: Jane Doe
323        email: jane@example.com
324        role: user
325        createdAt: '2024-01-15T10:30:00Z'
326        updatedAt: '2024-01-15T10:30:00Z'
327    CreateUserInput:
328      type: object
329      required:
330        - name
331        - email
332      properties:
333        name:
334          type: string
335          minLength: 1
336          maxLength: 255
337          description: Full name of the user
338        email:
339          type: string
340          format: email
341          description: Email address of the user
342        role:
343          type: string
344          enum:
345            - admin
346            - user
347            - viewer
348          default: user
349      example:
350        name: Jane Doe
351        email: jane@example.com
352        role: user
353    UpdateUserInput:
354      type: object
355      properties:
356        name:
357          type: string
358          minLength: 1
359          maxLength: 255
360        email:
361          type: string
362          format: email
363        role:
364          type: string
365          enum:
366            - admin
367            - user
368            - viewer
369      example:
370        name: Jane Smith
371        email: jane.smith@example.com
372    PaginationMeta:
373      type: object
374      properties:
375        total:
376          type: integer
377          description: Total number of items
378        page:
379          type: integer
380          description: Current page number
381        limit:
382          type: integer
383          description: Items per page
384        totalPages:
385          type: integer
386          description: Total number of pages
387    PaginatedUsers:
388      type: object
389      properties:
390        data:
391          type: array
392          items:
393            $ref: '#/components/schemas/User'
394        meta:
395          $ref: '#/components/schemas/PaginationMeta'
396    Error:
397      type: object
398      required:
399        - code
400        - message
401      properties:
402        code:
403          type: string
404          description: Machine-readable error code
405        message:
406          type: string
407          description: Human-readable error message
408        details:
409          type: array
410          items:
411            type: object
412            properties:
413              field:
414                type: string
415              message:
416                type: string
417          description: Optional field-level error details
418      example:
419        code: VALIDATION_FAILED
420        message: The provided payload is invalid.
421        details:
422          - field: email
423            message: Must be a valid email address
424    ErrorResponse:
425      type: object
426      properties:
427        error:
428          $ref: '#/components/schemas/Error'
429  securitySchemes:
430    bearerAuth:
431      type: http
432      scheme: bearer
433      bearerFormat: JWT
434      description: 'Enter your JWT token in the format: Bearer <token>'
435  responses:
436    Unauthorized:
437      description: Unauthorized - Invalid or missing authentication
438      content:
439        application/json:
440          schema:
441            $ref: '#/components/schemas/ErrorResponse'
442security:
443  - bearerAuth: []

Overview

OpenAPI Specification Generator

The OpenAPI Generator allows platform teams to bootstrap enterprise-compliant OpenAPI 3.x specifications without manually writing complex YAML structures.

A strongly typed OpenAPI spec is the foundation of modern API-first development, unlocking automated client SDK generation, server stubs, and live documentation using tools like Swagger UI, Redoc, or Stoplight. The generator produces YAML, JSON, and comprehensive API documentation.

Best Practices

Define standard error schemas globally inside `components/schemas` instead of rewriting error shapes on every endpoint. This reduces duplication and ensures consistent error responses.
Assign unique `operationId` values to every route. Client SDK generators use them to name the functions they output (e.g., `api.listUsers()`, `api.createUser()`).
Include detailed examples in your schema components. Mock servers (like Prism) use these examples to return realistic dummy data to your frontend team during development.
Add descriptions to every endpoint, parameter, and schema property. This improves documentation readability and helps API consumers understand expected behavior.

Common Mistakes

Using an unencrypted `http://` URL in the `servers` block for production environments. Always use HTTPS for production API servers.
Hardcoding security tokens or basic auth credentials into the `example` fields of request bodies or headers. Use placeholder values like YOUR_API_KEY_HERE.
Forgetting to apply the `security` array globally or per-endpoint after defining a `securityScheme`, leaving endpoints undocumented regarding authentication requirements.

Security Recommendations

Define security schemes in `components/securitySchemes` and apply them globally or per-endpoint using the `security` array.
For Bearer JWT authentication, always specify `bearerFormat: JWT` to help API consumers understand the expected token format.
API Key authentication via query parameters is less secure than header-based authentication. Prefer header-based API keys when possible.

Frequently Asked Questions

What is the difference between OpenAPI 3.0 and 3.1?

OpenAPI 3.1 aligns with JSON Schema 2020-12, adding support for nullable types using type: [string, null] instead of the nullable: true keyword. It also improves webhook support and adds better JSON Schema compatibility.

How do I generate a client SDK from my OpenAPI spec?

Use the OpenAPI Generator CLI: `npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./sdk`. This supports 50+ languages including TypeScript, Python, Go, Java, and more.

Can I import an existing OpenAPI spec to modify it?

Yes. You can paste your existing OpenAPI YAML or JSON into the import section. The tool will validate it and allow you to modify and enhance it with additional schemas, security schemes, and examples.