Initial commit
This commit is contained in:
Zhongwei Li
59
skills/documentation-architecture/templates/INDEX.md
Normal file
59
skills/documentation-architecture/templates/INDEX.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Documentation Templates
|
||||
|
||||
Copy-paste ready templates for API documentation, architecture docs, and OpenAPI specifications.
|
||||
|
||||
## Available Templates
|
||||
|
||||
### [API Endpoint Documentation](api-endpoint.md)
|
||||
|
||||
Complete template for documenting a single API endpoint with all required sections.
|
||||
|
||||
**Includes**: Method/path, description, authentication, request/response formats, error codes, rate limits, code examples
|
||||
|
||||
**Use when**: Documenting REST API endpoints, creating API reference pages
|
||||
|
||||
---
|
||||
|
||||
### [Architecture Document](architecture-doc.md)
|
||||
|
||||
Comprehensive template for system architecture documentation with Mermaid diagrams.
|
||||
|
||||
**Includes**: Executive summary, system overview, component descriptions, data flow, ADRs, security model
|
||||
|
||||
**Use when**: Documenting new systems, onboarding materials, architecture reviews
|
||||
|
||||
---
|
||||
|
||||
### [OpenAPI Specification](openapi-spec.yaml)
|
||||
|
||||
Starter OpenAPI 3.1 specification with common patterns and best practices.
|
||||
|
||||
**Includes**: Info object, servers, authentication, common schemas (errors, pagination), example endpoint
|
||||
|
||||
**Use when**: Starting new API documentation, generating from scratch
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Copy template file to your documentation directory
|
||||
2. Replace all `[FILL IN]` placeholders
|
||||
3. Remove optional sections if not needed
|
||||
4. Validate and test
|
||||
|
||||
## Template Customization
|
||||
|
||||
**For your project**:
|
||||
- Update company/project names
|
||||
- Adjust authentication schemes
|
||||
- Add project-specific error codes
|
||||
- Include relevant examples
|
||||
|
||||
**For your team**:
|
||||
- Add team-specific sections
|
||||
- Include internal links
|
||||
- Reference team tools/dashboards
|
||||
|
||||
---
|
||||
|
||||
Related: [Examples](../examples/INDEX.md) | [Reference](../reference/INDEX.md) | [Return to Agent](../docs-architect.md)
|
||||
191
skills/documentation-architecture/templates/api-endpoint.md
Normal file
191
skills/documentation-architecture/templates/api-endpoint.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# [METHOD] /api/v1/[resource]
|
||||
|
||||
[One sentence description of what this endpoint does]
|
||||
|
||||
## Authentication
|
||||
|
||||
**Required**: [Yes/No]
|
||||
**Roles**: [Admin, Member, Guest] _(if applicable)_
|
||||
**Scopes**: [read:resource, write:resource] _(if applicable)_
|
||||
|
||||
## Request
|
||||
|
||||
### Headers
|
||||
|
||||
| Header | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| `Authorization` | Yes | Bearer token: `Bearer <token>` |
|
||||
| `Content-Type` | Yes | `application/json` |
|
||||
| `X-Tenant-ID` | Yes | Tenant identifier _(if multi-tenant)_ |
|
||||
|
||||
### Path Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `[param_name]` | string | [Description] |
|
||||
|
||||
### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `[param_name]` | string | No | [default] | [Description] |
|
||||
| `page` | integer | No | 1 | Page number (min: 1) |
|
||||
| `per_page` | integer | No | 20 | Items per page (min: 1, max: 100) |
|
||||
|
||||
### Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `[field_name]` | string | Yes | [Description, validation rules] |
|
||||
| `[field_name]` | integer | No | [Description, validation rules] |
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"[field_name]": "value",
|
||||
"[field_name]": 123
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "res_1234567890abcdef",
|
||||
"[field_name]": "value",
|
||||
"created_at": "2024-01-15T10:30:00Z",
|
||||
"updated_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Success (201 Created)
|
||||
|
||||
**Headers**:
|
||||
- `Location: /api/v1/[resource]/res_1234567890abcdef`
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "res_1234567890abcdef",
|
||||
"[field_name]": "value",
|
||||
"created_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Responses
|
||||
|
||||
| Code | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| 400 | Bad Request - Validation failed | `{"error": "VALIDATION_ERROR", "message": "Field 'email' is invalid"}` |
|
||||
| 401 | Unauthorized - Missing or invalid token | `{"error": "UNAUTHORIZED", "message": "Invalid or missing authentication token"}` |
|
||||
| 403 | Forbidden - Insufficient permissions | `{"error": "FORBIDDEN", "message": "User lacks required role"}` |
|
||||
| 404 | Not Found - Resource doesn't exist | `{"error": "NOT_FOUND", "message": "Resource with id 'xyz' not found"}` |
|
||||
| 409 | Conflict - Resource already exists | `{"error": "CONFLICT", "message": "Resource with this identifier already exists"}` |
|
||||
| 429 | Too Many Requests - Rate limit exceeded | `{"error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded, retry after 60 seconds"}` |
|
||||
| 500 | Internal Server Error | `{"error": "INTERNAL_ERROR", "message": "An unexpected error occurred"}` |
|
||||
|
||||
**Error Response Schema**:
|
||||
```json
|
||||
{
|
||||
"error": "ERROR_CODE",
|
||||
"message": "Human-readable error message",
|
||||
"details": {
|
||||
"field": "field_name",
|
||||
"reason": "specific reason"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
- **Authenticated**: [1000] requests per hour
|
||||
- **Unauthenticated**: [100] requests per hour
|
||||
|
||||
**Response Headers**:
|
||||
- `X-RateLimit-Limit`: Maximum requests per hour
|
||||
- `X-RateLimit-Remaining`: Remaining requests in current window
|
||||
- `X-RateLimit-Reset`: Unix timestamp when limit resets
|
||||
|
||||
## Pagination
|
||||
|
||||
_(If endpoint returns paginated results)_
|
||||
|
||||
**Request**: Use `page` and `per_page` query parameters
|
||||
**Response**: Includes `pagination` object
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [...],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"per_page": 20,
|
||||
"total": 145,
|
||||
"total_pages": 8,
|
||||
"next_page": 2,
|
||||
"prev_page": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Code Examples
|
||||
|
||||
### TypeScript
|
||||
|
||||
```typescript
|
||||
const response = await fetch('https://api.greyhaven.com/[resource]', {
|
||||
method: '[METHOD]',
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`,
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
[field_name]: 'value'
|
||||
})
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
throw new Error(error.message);
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
console.log('[Resource] created:', data.id);
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import httpx
|
||||
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.[method](
|
||||
'https://api.greyhaven.com/[resource]',
|
||||
headers={'Authorization': f'Bearer {token}'},
|
||||
json={'[field_name]': 'value'}
|
||||
)
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
print(f'[Resource] created: {data["id"]}')
|
||||
```
|
||||
|
||||
### cURL
|
||||
|
||||
```bash
|
||||
curl -X [METHOD] https://api.greyhaven.com/[resource] \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"[field_name]": "value"
|
||||
}'
|
||||
```
|
||||
|
||||
## Changelog
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| v1.0.0 | 2024-01-15 | Initial release |
|
||||
|
||||
---
|
||||
|
||||
[Return to API Reference](../README.md)
|
||||
307
skills/documentation-architecture/templates/architecture-doc.md
Normal file
307
skills/documentation-architecture/templates/architecture-doc.md
Normal file
@@ -0,0 +1,307 @@
|
||||
# [System Name] Architecture
|
||||
|
||||
**Version**: [1.0.0]
|
||||
**Last Updated**: [YYYY-MM-DD]
|
||||
**Status**: [Draft / In Review / Approved]
|
||||
**Authors**: [Names]
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[2-3 paragraph high-level overview suitable for non-technical stakeholders. Include:]
|
||||
- What the system does
|
||||
- Key business value
|
||||
- Major technical decisions
|
||||
- Scale/performance characteristics
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [System Overview](#system-overview)
|
||||
- [Architecture Overview](#architecture-overview)
|
||||
- [Core Components](#core-components)
|
||||
- [Data Flow](#data-flow)
|
||||
- [Integration Points](#integration-points)
|
||||
- [Security Model](#security-model)
|
||||
- [Deployment Architecture](#deployment-architecture)
|
||||
- [Architecture Decision Records](#architecture-decision-records)
|
||||
- [Appendix](#appendix)
|
||||
|
||||
## System Overview
|
||||
|
||||
### Purpose
|
||||
|
||||
[What problem does this system solve?]
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Feature 1**: [Description]
|
||||
- **Feature 2**: [Description]
|
||||
- **Feature 3**: [Description]
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
| Requirement | Target | Current |
|
||||
|-------------|--------|---------|
|
||||
| Availability | 99.9% | 99.95% |
|
||||
| Response Time (p95) | <500ms | 320ms |
|
||||
| Throughput | 1000 req/s | 850 req/s |
|
||||
| Data Retention | 7 years | 7 years |
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### High-Level Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Client Layer"
|
||||
Browser[Web Browser]
|
||||
Mobile[Mobile App]
|
||||
end
|
||||
|
||||
subgraph "Edge Layer"
|
||||
Gateway[API Gateway]
|
||||
CDN[CDN]
|
||||
end
|
||||
|
||||
subgraph "Application Layer"
|
||||
Frontend[Frontend Service]
|
||||
Backend[Backend Service]
|
||||
end
|
||||
|
||||
subgraph "Data Layer"
|
||||
DB[(Database)]
|
||||
Cache[(Cache)]
|
||||
Storage[(Object Storage)]
|
||||
end
|
||||
|
||||
Browser --> Gateway
|
||||
Mobile --> Gateway
|
||||
Gateway --> Frontend
|
||||
Gateway --> Backend
|
||||
Frontend --> DB
|
||||
Backend --> DB
|
||||
Backend --> Cache
|
||||
Backend --> Storage
|
||||
```
|
||||
|
||||
### Technology Stack
|
||||
|
||||
| Layer | Technology | Version | Rationale |
|
||||
|-------|------------|---------|-----------|
|
||||
| Frontend | [Framework] | [x.y.z] | [Why chosen] |
|
||||
| Backend | [Framework] | [x.y.z] | [Why chosen] |
|
||||
| Database | [Database] | [x.y.z] | [Why chosen] |
|
||||
| Cache | [Cache] | [x.y.z] | [Why chosen] |
|
||||
| Deployment | [Platform] | [x.y.z] | [Why chosen] |
|
||||
|
||||
## Core Components
|
||||
|
||||
### [Component 1]: [Name]
|
||||
|
||||
**Purpose**: [What this component does]
|
||||
|
||||
**Responsibilities**:
|
||||
- [Responsibility 1]
|
||||
- [Responsibility 2]
|
||||
- [Responsibility 3]
|
||||
|
||||
**Technology**: [Framework/Language]
|
||||
**Repository**: [Link to repo]
|
||||
|
||||
**Key Interfaces**:
|
||||
- REST API: `POST /api/v1/[endpoint]`
|
||||
- WebSocket: `wss://[domain]/[path]`
|
||||
- Message Queue: `[queue-name]`
|
||||
|
||||
### [Component 2]: [Name]
|
||||
|
||||
[Same structure as Component 1]
|
||||
|
||||
## Data Flow
|
||||
|
||||
### [Flow 1]: [Name]
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant Frontend
|
||||
participant Backend
|
||||
participant DB
|
||||
|
||||
User->>Frontend: [Action]
|
||||
Frontend->>Backend: POST /api/[endpoint]
|
||||
Backend->>DB: Query/Update
|
||||
DB-->>Backend: Result
|
||||
Backend-->>Frontend: Response
|
||||
Frontend-->>User: Display result
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
1. [Step 1 description]
|
||||
2. [Step 2 description]
|
||||
3. [Step 3 description]
|
||||
|
||||
**Error Handling**:
|
||||
- [Error scenario 1]: [How handled]
|
||||
- [Error scenario 2]: [How handled]
|
||||
|
||||
## Integration Points
|
||||
|
||||
### External Service 1: [Service Name]
|
||||
|
||||
**Purpose**: [Why we integrate with this service]
|
||||
**Protocol**: [REST API / GraphQL / gRPC]
|
||||
**Authentication**: [Method]
|
||||
**Rate Limits**: [X requests per Y]
|
||||
**SLA**: [Uptime guarantee]
|
||||
|
||||
**Endpoints Used**:
|
||||
- `[METHOD] /[path]` - [Purpose]
|
||||
- `[METHOD] /[path]` - [Purpose]
|
||||
|
||||
**Fallback Strategy**: [What happens if service unavailable]
|
||||
|
||||
### External Service 2: [Service Name]
|
||||
|
||||
[Same structure as External Service 1]
|
||||
|
||||
## Security Model
|
||||
|
||||
### Authentication
|
||||
|
||||
**Method**: [JWT / OAuth2 / API Key]
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant Auth
|
||||
participant Service
|
||||
|
||||
User->>Auth: Login with credentials
|
||||
Auth-->>User: JWT token
|
||||
User->>Service: Request + JWT
|
||||
Service->>Service: Validate token
|
||||
Service-->>User: Response
|
||||
```
|
||||
|
||||
### Authorization
|
||||
|
||||
**Model**: [RBAC / ABAC / ACL]
|
||||
|
||||
**Roles**:
|
||||
- `admin`: [Permissions]
|
||||
- `member`: [Permissions]
|
||||
- `guest`: [Permissions]
|
||||
|
||||
### Data Protection
|
||||
|
||||
**Encryption**:
|
||||
- At rest: [Method, algorithm]
|
||||
- In transit: TLS 1.3
|
||||
- Database: [Encryption method]
|
||||
|
||||
**Multi-Tenancy**:
|
||||
- Isolation method: [Row-Level Security / Separate DBs / Separate Schemas]
|
||||
- Tenant identification: [Header / Subdomain / Path]
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
### Environments
|
||||
|
||||
| Environment | Purpose | URL | Auto-Deploy |
|
||||
|-------------|---------|-----|-------------|
|
||||
| Development | Feature development | https://dev.[domain] | On PR |
|
||||
| Staging | Pre-production testing | https://staging.[domain] | On merge to main |
|
||||
| Production | Live system | https://[domain] | On release tag |
|
||||
|
||||
### Infrastructure
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Production"
|
||||
LB[Load Balancer]
|
||||
App1[App Server 1]
|
||||
App2[App Server 2]
|
||||
App3[App Server 3]
|
||||
DB[(Primary DB)]
|
||||
Replica[(Read Replica)]
|
||||
end
|
||||
|
||||
LB --> App1
|
||||
LB --> App2
|
||||
LB --> App3
|
||||
App1 --> DB
|
||||
App2 --> DB
|
||||
App3 --> DB
|
||||
App1 -.read.-> Replica
|
||||
App2 -.read.-> Replica
|
||||
App3 -.read.-> Replica
|
||||
DB -.replication.-> Replica
|
||||
```
|
||||
|
||||
**Resources**:
|
||||
- App Servers: [X instances, Y CPU, Z GB RAM]
|
||||
- Database: [Specifications]
|
||||
- Cache: [Specifications]
|
||||
|
||||
### CI/CD Pipeline
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Code[Code Push] --> Tests[Run Tests]
|
||||
Tests --> Build[Build]
|
||||
Build --> Deploy[Deploy to Staging]
|
||||
Deploy --> Smoke[Smoke Tests]
|
||||
Smoke --> Approve{Manual Approve?}
|
||||
Approve -->|Yes| Prod[Deploy to Production]
|
||||
Approve -->|No| Wait[Wait]
|
||||
```
|
||||
|
||||
## Architecture Decision Records
|
||||
|
||||
### ADR-001: [Decision Title]
|
||||
|
||||
**Date**: [YYYY-MM-DD]
|
||||
**Status**: [Accepted / Superseded / Deprecated]
|
||||
**Decision Makers**: [Names]
|
||||
|
||||
**Context**: [What circumstances led to this decision?]
|
||||
|
||||
**Decision**: [What was decided?]
|
||||
|
||||
**Alternatives Considered**:
|
||||
1. **[Option 1]**: [Pros/Cons]
|
||||
2. **[Option 2]**: [Pros/Cons]
|
||||
|
||||
**Consequences**:
|
||||
- **Positive**: [Benefit 1], [Benefit 2]
|
||||
- **Negative**: [Trade-off 1], [Trade-off 2]
|
||||
|
||||
**Implementation**: [How was this implemented?]
|
||||
|
||||
### ADR-002: [Decision Title]
|
||||
|
||||
[Same structure as ADR-001]
|
||||
|
||||
## Appendix
|
||||
|
||||
### Glossary
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| [Term] | [Definition] |
|
||||
|
||||
### References
|
||||
|
||||
- Architecture Diagrams: [Link]
|
||||
- API Documentation: [Link]
|
||||
- Runbooks: [Link]
|
||||
- Monitoring Dashboard: [Link]
|
||||
|
||||
### Related Documentation
|
||||
|
||||
- [Link to related doc 1]
|
||||
- [Link to related doc 2]
|
||||
|
||||
---
|
||||
|
||||
[Return to Documentation Index](../README.md)
|
||||
429
skills/documentation-architecture/templates/openapi-spec.yaml
Normal file
429
skills/documentation-architecture/templates/openapi-spec.yaml
Normal file
@@ -0,0 +1,429 @@
|
||||
openapi: 3.1.0
|
||||
|
||||
info:
|
||||
title: [Your API Name]
|
||||
version: 1.0.0
|
||||
description: |
|
||||
[Brief description of your API]
|
||||
|
||||
## Authentication
|
||||
All endpoints require JWT authentication via Bearer token in Authorization header.
|
||||
|
||||
## Rate Limiting
|
||||
- Authenticated: 1000 requests/hour
|
||||
- Unauthenticated: 100 requests/hour
|
||||
|
||||
## Base URL
|
||||
Production: https://api.yourdomain.com
|
||||
Staging: https://api-staging.yourdomain.com
|
||||
|
||||
contact:
|
||||
name: [Your Team Name]
|
||||
email: support@yourdomain.com
|
||||
url: https://docs.yourdomain.com
|
||||
|
||||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
|
||||
servers:
|
||||
- url: https://api.yourdomain.com
|
||||
description: Production
|
||||
- url: https://api-staging.yourdomain.com
|
||||
description: Staging
|
||||
- url: http://localhost:3000
|
||||
description: Local development
|
||||
|
||||
# Global security requirement (can be overridden per endpoint)
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
tags:
|
||||
- name: users
|
||||
description: User management operations
|
||||
- name: authentication
|
||||
description: Authentication and authorization
|
||||
|
||||
paths:
|
||||
/auth/login:
|
||||
post:
|
||||
summary: User login
|
||||
description: Authenticate user with email and password
|
||||
operationId: login
|
||||
tags:
|
||||
- authentication
|
||||
security: [] # No auth required for login
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LoginRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Login successful
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LoginResponse'
|
||||
'400':
|
||||
$ref: '#/components/responses/BadRequest'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'429':
|
||||
$ref: '#/components/responses/TooManyRequests'
|
||||
|
||||
/users:
|
||||
get:
|
||||
summary: List users
|
||||
description: Retrieve a paginated list of users
|
||||
operationId: listUsers
|
||||
tags:
|
||||
- users
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/PageParam'
|
||||
- $ref: '#/components/parameters/PerPageParam'
|
||||
- name: role
|
||||
in: query
|
||||
description: Filter by user role
|
||||
schema:
|
||||
type: string
|
||||
enum: [admin, member, guest]
|
||||
responses:
|
||||
'200':
|
||||
description: Users retrieved successfully
|
||||
headers:
|
||||
X-RateLimit-Limit:
|
||||
$ref: '#/components/headers/X-RateLimit-Limit'
|
||||
X-RateLimit-Remaining:
|
||||
$ref: '#/components/headers/X-RateLimit-Remaining'
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/PaginatedUsers'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'429':
|
||||
$ref: '#/components/responses/TooManyRequests'
|
||||
|
||||
post:
|
||||
summary: Create user
|
||||
description: Create a new user account
|
||||
operationId: createUser
|
||||
tags:
|
||||
- users
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserCreate'
|
||||
responses:
|
||||
'201':
|
||||
description: User created successfully
|
||||
headers:
|
||||
Location:
|
||||
description: URL of created user
|
||||
schema:
|
||||
type: string
|
||||
example: /users/usr_1234567890abcdef
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
'400':
|
||||
$ref: '#/components/responses/BadRequest'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'409':
|
||||
$ref: '#/components/responses/Conflict'
|
||||
|
||||
/users/{user_id}:
|
||||
get:
|
||||
summary: Get user by ID
|
||||
description: Retrieve a single user by their unique identifier
|
||||
operationId: getUser
|
||||
tags:
|
||||
- users
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/UserIdParam'
|
||||
responses:
|
||||
'200':
|
||||
description: User retrieved successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: JWT token obtained from /auth/login endpoint
|
||||
|
||||
parameters:
|
||||
UserIdParam:
|
||||
name: user_id
|
||||
in: path
|
||||
required: true
|
||||
description: User identifier
|
||||
schema:
|
||||
type: string
|
||||
pattern: ^usr_[a-z0-9]{16}$
|
||||
example: usr_1234567890abcdef
|
||||
|
||||
PageParam:
|
||||
name: page
|
||||
in: query
|
||||
description: Page number (1-indexed)
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
default: 1
|
||||
example: 1
|
||||
|
||||
PerPageParam:
|
||||
name: per_page
|
||||
in: query
|
||||
description: Items per page
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
default: 20
|
||||
example: 20
|
||||
|
||||
headers:
|
||||
X-RateLimit-Limit:
|
||||
description: Maximum requests per hour
|
||||
schema:
|
||||
type: integer
|
||||
example: 1000
|
||||
|
||||
X-RateLimit-Remaining:
|
||||
description: Remaining requests in current window
|
||||
schema:
|
||||
type: integer
|
||||
example: 847
|
||||
|
||||
X-RateLimit-Reset:
|
||||
description: Unix timestamp when limit resets
|
||||
schema:
|
||||
type: integer
|
||||
example: 1699564800
|
||||
|
||||
schemas:
|
||||
LoginRequest:
|
||||
type: object
|
||||
required: [email, password]
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
examples: [user@example.com]
|
||||
password:
|
||||
type: string
|
||||
minLength: 8
|
||||
examples: [secure123]
|
||||
|
||||
LoginResponse:
|
||||
type: object
|
||||
required: [token, user]
|
||||
properties:
|
||||
token:
|
||||
type: string
|
||||
description: JWT authentication token
|
||||
user:
|
||||
$ref: '#/components/schemas/User'
|
||||
|
||||
UserCreate:
|
||||
type: object
|
||||
required: [email, password]
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
examples: [user@example.com]
|
||||
password:
|
||||
type: string
|
||||
minLength: 8
|
||||
examples: [secure123]
|
||||
name:
|
||||
type: string
|
||||
examples: [John Doe]
|
||||
role:
|
||||
type: string
|
||||
enum: [admin, member, guest]
|
||||
default: member
|
||||
|
||||
User:
|
||||
type: object
|
||||
required: [id, email, role, created_at]
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
pattern: ^usr_[a-z0-9]{16}$
|
||||
examples: [usr_1234567890abcdef]
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
examples: [user@example.com]
|
||||
name:
|
||||
type: [string, 'null']
|
||||
examples: [John Doe]
|
||||
role:
|
||||
type: string
|
||||
enum: [admin, member, guest]
|
||||
examples: [member]
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
examples: ["2024-01-15T10:30:00Z"]
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
examples: ["2024-01-15T10:30:00Z"]
|
||||
|
||||
PaginatedUsers:
|
||||
type: object
|
||||
required: [data, pagination]
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/User'
|
||||
pagination:
|
||||
$ref: '#/components/schemas/PaginationMeta'
|
||||
|
||||
PaginationMeta:
|
||||
type: object
|
||||
required: [page, per_page, total, total_pages]
|
||||
properties:
|
||||
page:
|
||||
type: integer
|
||||
minimum: 1
|
||||
examples: [1]
|
||||
per_page:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
examples: [20]
|
||||
total:
|
||||
type: integer
|
||||
examples: [145]
|
||||
total_pages:
|
||||
type: integer
|
||||
examples: [8]
|
||||
next_page:
|
||||
type: [integer, 'null']
|
||||
examples: [2]
|
||||
prev_page:
|
||||
type: [integer, 'null']
|
||||
examples: [null]
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
required: [error, message]
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
description: Error code (UPPERCASE_SNAKE_CASE)
|
||||
examples: [VALIDATION_ERROR, UNAUTHORIZED, NOT_FOUND]
|
||||
message:
|
||||
type: string
|
||||
description: Human-readable error message
|
||||
examples: [Validation failed for field 'email']
|
||||
details:
|
||||
type: object
|
||||
description: Additional error context
|
||||
additionalProperties: true
|
||||
examples:
|
||||
- field: email
|
||||
reason: Invalid format
|
||||
|
||||
responses:
|
||||
BadRequest:
|
||||
description: Bad request (validation error)
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
validation_error:
|
||||
value:
|
||||
error: VALIDATION_ERROR
|
||||
message: Validation failed for field 'email'
|
||||
details:
|
||||
field: email
|
||||
reason: Invalid email format
|
||||
|
||||
Unauthorized:
|
||||
description: Unauthorized (invalid or missing authentication)
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
missing_token:
|
||||
value:
|
||||
error: UNAUTHORIZED
|
||||
message: Authentication token required
|
||||
invalid_token:
|
||||
value:
|
||||
error: UNAUTHORIZED
|
||||
message: Invalid or expired authentication token
|
||||
|
||||
Forbidden:
|
||||
description: Forbidden (insufficient permissions)
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
insufficient_role:
|
||||
value:
|
||||
error: FORBIDDEN
|
||||
message: User lacks required role
|
||||
|
||||
NotFound:
|
||||
description: Resource not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
not_found:
|
||||
value:
|
||||
error: NOT_FOUND
|
||||
message: Resource with id 'xyz' not found
|
||||
|
||||
Conflict:
|
||||
description: Conflict (resource already exists)
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
already_exists:
|
||||
value:
|
||||
error: CONFLICT
|
||||
message: Resource with this identifier already exists
|
||||
|
||||
TooManyRequests:
|
||||
description: Rate limit exceeded
|
||||
headers:
|
||||
X-RateLimit-Reset:
|
||||
$ref: '#/components/headers/X-RateLimit-Reset'
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
rate_limit:
|
||||
value:
|
||||
error: RATE_LIMIT_EXCEEDED
|
||||
message: Rate limit exceeded, retry after 60 seconds
|
||||
Reference in New Issue
Block a user