Documenting APIs

paths:
  /users/{userId}:
    get:
      summary: Retrieve user by ID
      description: Returns full user profile if requester has access.
      operationId: getUser
      tags: [Users]
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200': { $ref: '#/components/responses/User' }
        '404': { $ref: '#/components/responses/NotFound' }

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:    { type: string, format: uuid }
        email: { type: string, format: email, example: "alice@example.com" }
        role:  { type: string, enum: [admin, user, guest] }
        createdAt: { type: string, format: date-time, readOnly: true }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read:users:  Read user data
            write:users: Modify user data
security:
  - bearerAuth: []