📋

openapi: 3.0.3
info:
  title: My API
  description: API description
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

paths:
  /users:
    get:
      summary: List users
      responses:
        "200":
          description: Success

paths:
  /users:
    get:
      summary: List all users
      operationId: listUsers
      tags:
        - Users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        "200":
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUser"
      responses:
        "201":
          description: Created

paths:
  /users/{userId}:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get user by ID
      responses:
        "200":
          description: Success
        "404":
          description: Not found
    put:
      summary: Update user
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUser"
      responses:
        "200":
          description: Updated
    delete:
      summary: Delete user
      responses:
        "204":
          description: Deleted

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 1
          maxLength: 100
        age:
          type: integer
          minimum: 0
          maximum: 150
        role:
          type: string
          enum: [admin, user, guest]
          default: user
        createdAt:
          type: string
          format: date-time
        tags:
          type: array
          items:
            type: string

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        user:
          $ref: "#/components/schemas/User"
        items:
          type: array
          items:
            $ref: "#/components/schemas/OrderItem"
    
    OrderItem:
      type: object
      properties:
        productId:
          type: string
        quantity:
          type: integer
        price:
          type: number
          format: double
    
    # Composition
    CreateUser:
      allOf:
        - $ref: "#/components/schemas/User"
        - type: object
          required:
            - password
          properties:
            password:
              type: string

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
    
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read: Read access
            write: Write access

# Global security
security:
  - bearerAuth: []

# Per-operation security
paths:
  /public:
    get:
      security: []  # No auth required
  /admin:
    get:
      security:
        - bearerAuth: []
        - oauth2: [admin]

components:
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    
    Unauthorized:
      description: Authentication required
      headers:
        WWW-Authenticate:
          schema:
            type: string
    
    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
              errors:
                type: array
                items:
                  type: object
                  properties:
                    field:
                      type: string
                    message:
                      type: string

paths:
  /users/{id}:
    get:
      responses:
        "200":
          description: Success
        "404":
          $ref: "#/components/responses/NotFound"