08-api-documentation

Primary Role: Create comprehensive, developer-friendly API documentation. Boundaries: • ✅ OpenAPI specs, SDK generation, code examples, developer portals • ✅ Changelog management, versioning documentation • ❌ API design decisions (delegate to Agent 01) • ❌ Implementation details (delegate to Agent 02) • ❌ Security specifications (delegate to Agent 05)

`yaml openapi: 3.1.0 info: title: User Management API description: | API for managing users, teams, and permissions. ## Authentication All endpoints require Bearer token authentication. ## Rate Limiting • 100 requests per 15 minutes for authenticated users • 10 requests per 15 minutes for unauthenticated ## Versioning API version is specified in the URL path: /api/v1/... version: 1.0.0 contact: name: API Support email: api-support@example.com url: https://docs.example.com license: name: MIT url: https://opensource.org/licenses/MIT servers: • url: https://api.example.com description: Production • url: https://staging-api.example.com description: Staging • url: http://localhost:3000 description: Development tags: • name: Users description: User management operations • name: Teams description: Team management operations paths: /api/v1/users: get: operationId: listUsers summary: List all users description: Returns a paginated list of users with optional filtering. tags: [Users] security: • bearerAuth: [] parameters: • $ref: '#/components/parameters/PageParam' • $ref: '#/components/parameters/LimitParam' • name: status in: query schema: type: string enum: [active, inactive, banned] description: Filter by user status • name: search in: query schema: type: string minLength: 2 description: Search by name or email responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/UserListResponse' examples: default: $ref: '#/components/examples/UserListExample' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' post: operationId: createUser summary: Create a new user tags: [Users] security: • bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' examples: basic: summary: Basic user creation value: email: user@example.com name: John Doe password: SecureP@ss123! responses: '201': description: User created content: application/json: schema: $ref: '#/components/schemas/UserResponse' headers: Location: schema: type: string description: URL of created user '400': $ref: '#/components/responses/ValidationError' '409': description: Email already exists content: application/json: schema: $ref: '#/components/schemas/Error' /api/v1/users/{userId}: parameters: • $ref: '#/components/parameters/UserIdParam' get: operationId: getUser summary: Get user by ID tags: [Users] security: • bearerAuth: [] responses: '200': description: User found content: application/json: schema: $ref: '#/components/schemas/UserResponse' '404': $ref: '#/components/responses/NotFound' patch: operationId: updateUser summary: Update user tags: [Users] security: • bearerAuth: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateUserRequest' responses: '200': description: User updated content: application/json: schema: $ref: '#/components/schemas/UserResponse' delete: operationId: deleteUser summary: Delete user description: | Permanently deletes a user and all associated data. This action cannot be undone. tags: [Users] security: • bearerAuth: [] responses: '204': description: User deleted components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token obtained from /auth/login parameters: UserIdParam: name: userId in: path required: true schema: type: string format: uuid description: Unique user identifier PageParam: name: page in: query schema: type: integer minimum: 1 default: 1 description: Page number LimitParam: name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 20 description: Items per page schemas: User: type: object required: [id, email, name, status, createdAt] properties: id: type: string format: uuid readOnly: true email: type: string format: email maxLength: 255 name: type: string minLength: 1 maxLength: 100 status: type: string enum: [active, inactive, banned] avatar: type: string format: uri nullable: true createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true CreateUserRequest: type: object required: [email, name, password] properties: email: type: string format: email name: type: string minLength: 1 maxLength: 100 password: type: string format: password minLength: 12 description: Must contain uppercase, lowercase, number, and special character UpdateUserRequest: type: object properties: name: type: string minLength: 1 maxLength: 100 status: type: string enum: [active, inactive] UserResponse: type: object properties: data: $ref: '#/components/schemas/User' meta: $ref: '#/components/schemas/ResponseMeta' UserListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/User' pagination: $ref: '#/components/schemas/Pagination' meta: $ref: '#/components/schemas/ResponseMeta' Pagination: type: object properties: page: type: integer limit: type: integer total: type: integer totalPages: type: integer hasNext: type: boolean hasPrev: type: boolean ResponseMeta: type: object properties: requestId: type: string timestamp: type: string format: date-time version: typ