openapi: 3.1.0 info: title: "{Project Name} API" description: | REST API for {Project Name}. All endpoints require Bearer JWT authentication unless marked as public. version: 1.0.0 contact: name: "{Project Name} Engineering" servers: - url: https://api.{project}.railway.app/api/v1 description: Production (prototype) - url: http://localhost:8000/api/v1 description: Local development security: - BearerAuth: [] tags: - name: auth description: Authentication and session management - name: users description: User profile management # Add more tags per resource paths: /auth/register: post: tags: [auth] summary: Create a new account security: [] requestBody: required: true content: application/json: schema: type: object required: [email, password, name] properties: email: type: string format: email example: user@example.com password: type: string minLength: 8 example: "SecurePass123!" name: type: string example: "Jane Doe" responses: "201": description: Account created successfully content: application/json: schema: $ref: "#/components/schemas/AuthResponse" "409": description: Email already registered content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": $ref: "#/components/responses/ValidationError" /auth/login: post: tags: [auth] summary: Authenticate and receive tokens security: [] requestBody: required: true content: application/json: schema: type: object required: [email, password] properties: email: type: string format: email password: type: string responses: "200": description: Authentication successful content: application/json: schema: $ref: "#/components/schemas/AuthResponse" "401": description: Invalid credentials content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /auth/refresh: post: tags: [auth] summary: Refresh access token using refresh token security: [] requestBody: required: true content: application/json: schema: type: object required: [refresh_token] properties: refresh_token: type: string responses: "200": description: Token refreshed content: application/json: schema: $ref: "#/components/schemas/AuthResponse" "401": description: Invalid or expired refresh token content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /users/me: get: tags: [users] summary: Get current user profile responses: "200": description: User profile content: application/json: schema: allOf: - $ref: "#/components/schemas/DataEnvelope" - type: object properties: data: $ref: "#/components/schemas/User" "401": $ref: "#/components/responses/Unauthorized" # Add resource endpoints here following the same pattern components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT schemas: User: type: object properties: id: type: string format: uuid example: "550e8400-e29b-41d4-a716-446655440000" email: type: string format: email name: type: string avatar_url: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time AuthResponse: type: object properties: data: type: object properties: access_token: type: string refresh_token: type: string token_type: type: string example: bearer expires_in: type: integer description: Access token TTL in seconds example: 900 user: $ref: "#/components/schemas/User" error: type: "null" DataEnvelope: type: object properties: data: description: Response payload meta: $ref: "#/components/schemas/PaginationMeta" error: type: "null" PaginationMeta: type: object nullable: true properties: page: type: integer example: 1 per_page: type: integer example: 20 total: type: integer example: 100 total_pages: type: integer example: 5 ErrorResponse: type: object properties: data: type: "null" error: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: "Human-readable error message" details: type: array items: type: object properties: field: type: string message: type: string responses: Unauthorized: description: Missing or invalid authentication token content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" ValidationError: description: Request validation failed content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" NotFound: description: Resource not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse"