Critical Patterns

Schema Definition (REQUIRED)

components: schemas: User: type: object description: Represents a user in the system required: - id - email properties: id: type: string format: uuid description: Unique identifier example: "123e4567-e89b-12d3-a456-426614174000" email: type: string format: email description: User's email address example: "user@example.com" name: type: string description: User's full name example: "John Doe"

Endpoint Documentation (REQUIRED)

paths: /users/{userId}: get: summary: Get user by ID description: | Retrieves detailed information about a specific user. Requires authentication. operationId: getUserById tags: - Users parameters: - name: userId in: path required: true schema: type: string format: uuid responses: '200': description: User found successfully content: application/json: schema: $ref: '#/components/schemas/User' '404': description: User not found '401': description: Authentication required

Decision Tree

Need reusable schema? → Define in components/schemas Need auth info? → Use securitySchemes Need examples? → Add example field Need multiple formats? → Use content negotiation Need error response? → Define error schema

Code Examples

Error Response

components: schemas: Error: type: object required: - code - message properties: code: type: string example: "USER_NOT_FOUND" message: type: string example: "User with specified ID does not exist"

Authentication

components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT

security:

• bearerAuth: []

Commands

Validate spec

npx @redocly/cli lint openapi.yaml

Generate docs

npx @redocly/cli build-docs openapi.yaml

Generate client

npx openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client