openapi

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