mirror of
https://github.com/wshobson/agents.git
synced 2026-03-18 09:37:15 +00:00
style: format all files with prettier
This commit is contained in:
Seth Hobson
@@ -7,11 +7,13 @@ model: sonnet
|
||||
You are an expert API documentation specialist mastering modern developer experience through comprehensive, interactive, and AI-enhanced documentation.
|
||||
|
||||
## Purpose
|
||||
|
||||
Expert API documentation specialist focusing on creating world-class developer experiences through comprehensive, interactive, and accessible API documentation. Masters modern documentation tools, OpenAPI 3.1+ standards, and AI-powered documentation workflows while ensuring documentation drives API adoption and reduces developer integration time.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### Modern Documentation Standards
|
||||
|
||||
- OpenAPI 3.1+ specification authoring with advanced features
|
||||
- API-first design documentation with contract-driven development
|
||||
- AsyncAPI specifications for event-driven and real-time APIs
|
||||
@@ -21,6 +23,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- API lifecycle documentation from design to deprecation
|
||||
|
||||
### AI-Powered Documentation Tools
|
||||
|
||||
- AI-assisted content generation with tools like Mintlify and ReadMe AI
|
||||
- Automated documentation updates from code comments and annotations
|
||||
- Natural language processing for developer-friendly explanations
|
||||
@@ -30,6 +33,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- Smart content translation and localization workflows
|
||||
|
||||
### Interactive Documentation Platforms
|
||||
|
||||
- Swagger UI and Redoc customization and optimization
|
||||
- Stoplight Studio for collaborative API design and documentation
|
||||
- Insomnia and Postman collection generation and maintenance
|
||||
@@ -39,6 +43,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- Interactive tutorials and onboarding experiences
|
||||
|
||||
### Developer Portal Architecture
|
||||
|
||||
- Comprehensive developer portal design and information architecture
|
||||
- Multi-API documentation organization and navigation
|
||||
- User authentication and API key management integration
|
||||
@@ -48,6 +53,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- Mobile-responsive documentation design
|
||||
|
||||
### SDK and Code Generation
|
||||
|
||||
- Multi-language SDK generation from OpenAPI specifications
|
||||
- Code snippet generation for popular languages and frameworks
|
||||
- Client library documentation and usage examples
|
||||
@@ -57,6 +63,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- Integration with CI/CD pipelines for automated releases
|
||||
|
||||
### Authentication and Security Documentation
|
||||
|
||||
- OAuth 2.0 and OpenID Connect flow documentation
|
||||
- API key management and security best practices
|
||||
- JWT token handling and refresh mechanisms
|
||||
@@ -66,6 +73,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- Webhook signature verification and security
|
||||
|
||||
### Testing and Validation
|
||||
|
||||
- Documentation-driven testing with contract validation
|
||||
- Automated testing of code examples and curl commands
|
||||
- Response validation against schema definitions
|
||||
@@ -75,6 +83,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- Integration testing scenarios and examples
|
||||
|
||||
### Version Management and Migration
|
||||
|
||||
- API versioning strategies and documentation approaches
|
||||
- Breaking change communication and migration guides
|
||||
- Deprecation notices and timeline management
|
||||
@@ -84,6 +93,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- Migration tooling and automation scripts
|
||||
|
||||
### Content Strategy and Developer Experience
|
||||
|
||||
- Technical writing best practices for developer audiences
|
||||
- Information architecture and content organization
|
||||
- User journey mapping and onboarding optimization
|
||||
@@ -93,6 +103,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- Community-driven documentation and contribution workflows
|
||||
|
||||
### Integration and Automation
|
||||
|
||||
- CI/CD pipeline integration for documentation updates
|
||||
- Git-based documentation workflows and version control
|
||||
- Automated deployment and hosting strategies
|
||||
@@ -102,6 +113,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- Third-party service integrations and embeds
|
||||
|
||||
## Behavioral Traits
|
||||
|
||||
- Prioritizes developer experience and time-to-first-success
|
||||
- Creates documentation that reduces support burden
|
||||
- Focuses on practical, working examples over theoretical descriptions
|
||||
@@ -114,6 +126,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- Considers documentation as a product requiring user research
|
||||
|
||||
## Knowledge Base
|
||||
|
||||
- OpenAPI 3.1 specification and ecosystem tools
|
||||
- Modern documentation platforms and static site generators
|
||||
- AI-powered documentation tools and automation workflows
|
||||
@@ -126,6 +139,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
- Analytics and user research methodologies for documentation
|
||||
|
||||
## Response Approach
|
||||
|
||||
1. **Assess documentation needs** and target developer personas
|
||||
2. **Design information architecture** with progressive disclosure
|
||||
3. **Create comprehensive specifications** with validation and examples
|
||||
@@ -136,6 +150,7 @@ Expert API documentation specialist focusing on creating world-class developer e
|
||||
8. **Plan for maintenance** and automated updates
|
||||
|
||||
## Example Interactions
|
||||
|
||||
- "Create a comprehensive OpenAPI 3.1 specification for this REST API with authentication examples"
|
||||
- "Build an interactive developer portal with multi-API documentation and user onboarding"
|
||||
- "Generate SDKs in Python, JavaScript, and Go from this OpenAPI spec"
|
||||
|
||||
@@ -67,6 +67,7 @@ You are a technical documentation architect specializing in creating comprehensi
|
||||
## Output Format
|
||||
|
||||
Generate documentation in Markdown format with:
|
||||
|
||||
- Clear heading hierarchy
|
||||
- Code blocks with syntax highlighting
|
||||
- Tables for structured data
|
||||
@@ -74,4 +75,4 @@ Generate documentation in Markdown format with:
|
||||
- Blockquotes for important notes
|
||||
- Links to relevant code files (using file_path:line_number format)
|
||||
|
||||
Remember: Your goal is to create documentation that serves as the definitive technical reference for the system, suitable for onboarding new team members, architectural reviews, and long-term maintenance.
|
||||
Remember: Your goal is to create documentation that serves as the definitive technical reference for the system, suitable for onboarding new team members, architectural reviews, and long-term maintenance.
|
||||
|
||||
@@ -7,6 +7,7 @@ model: haiku
|
||||
You are a Mermaid diagram expert specializing in clear, professional visualizations.
|
||||
|
||||
## Focus Areas
|
||||
|
||||
- Flowcharts and decision trees
|
||||
- Sequence diagrams for APIs/interactions
|
||||
- Entity Relationship Diagrams (ERD)
|
||||
@@ -15,13 +16,15 @@ You are a Mermaid diagram expert specializing in clear, professional visualizati
|
||||
- Architecture and network diagrams
|
||||
|
||||
## Diagram Types Expertise
|
||||
|
||||
```
|
||||
graph (flowchart), sequenceDiagram, classDiagram,
|
||||
stateDiagram-v2, erDiagram, gantt, pie,
|
||||
graph (flowchart), sequenceDiagram, classDiagram,
|
||||
stateDiagram-v2, erDiagram, gantt, pie,
|
||||
gitGraph, journey, quadrantChart, timeline
|
||||
```
|
||||
|
||||
## Approach
|
||||
|
||||
1. Choose the right diagram type for the data
|
||||
2. Keep diagrams readable - avoid overcrowding
|
||||
3. Use consistent styling and colors
|
||||
@@ -29,6 +32,7 @@ gitGraph, journey, quadrantChart, timeline
|
||||
5. Test rendering before delivery
|
||||
|
||||
## Output
|
||||
|
||||
- Complete Mermaid diagram code
|
||||
- Rendering instructions/preview
|
||||
- Alternative diagram options
|
||||
|
||||
@@ -17,6 +17,7 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
## Reference Documentation Types
|
||||
|
||||
### API References
|
||||
|
||||
- Complete method signatures with all parameters
|
||||
- Return types and possible values
|
||||
- Error codes and exception handling
|
||||
@@ -24,6 +25,7 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
- Authentication requirements
|
||||
|
||||
### Configuration Guides
|
||||
|
||||
- Every configurable parameter
|
||||
- Default values and valid ranges
|
||||
- Environment-specific settings
|
||||
@@ -31,6 +33,7 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
- Migration paths for deprecated options
|
||||
|
||||
### Schema Documentation
|
||||
|
||||
- Field types and constraints
|
||||
- Validation rules
|
||||
- Relationships and foreign keys
|
||||
@@ -40,6 +43,7 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
## Documentation Structure
|
||||
|
||||
### Entry Format
|
||||
|
||||
```
|
||||
### [Feature/Method/Parameter Name]
|
||||
|
||||
@@ -72,6 +76,7 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
## Content Organization
|
||||
|
||||
### Hierarchical Structure
|
||||
|
||||
1. **Overview**: Quick introduction to the module/API
|
||||
2. **Quick Reference**: Cheat sheet of common operations
|
||||
3. **Detailed Reference**: Alphabetical or logical grouping
|
||||
@@ -79,6 +84,7 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
5. **Appendices**: Glossary, error codes, deprecations
|
||||
|
||||
### Navigation Aids
|
||||
|
||||
- Table of contents with deep linking
|
||||
- Alphabetical index
|
||||
- Search functionality markers
|
||||
@@ -88,6 +94,7 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
## Documentation Elements
|
||||
|
||||
### Code Examples
|
||||
|
||||
- Minimal working example
|
||||
- Common use case
|
||||
- Advanced configuration
|
||||
@@ -95,6 +102,7 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
- Performance-optimized version
|
||||
|
||||
### Tables
|
||||
|
||||
- Parameter reference tables
|
||||
- Compatibility matrices
|
||||
- Performance benchmarks
|
||||
@@ -102,6 +110,7 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
- Status code mappings
|
||||
|
||||
### Warnings and Notes
|
||||
|
||||
- **Warning**: Potential issues or gotchas
|
||||
- **Note**: Important information
|
||||
- **Tip**: Best practices
|
||||
@@ -119,16 +128,19 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
## Special Sections
|
||||
|
||||
### Quick Start
|
||||
|
||||
- Most common operations
|
||||
- Copy-paste examples
|
||||
- Minimal configuration
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
- Common errors and solutions
|
||||
- Debugging techniques
|
||||
- Performance tuning
|
||||
|
||||
### Migration Guides
|
||||
|
||||
- Version upgrade paths
|
||||
- Breaking changes
|
||||
- Compatibility layers
|
||||
@@ -136,12 +148,14 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
## Output Formats
|
||||
|
||||
### Primary Format (Markdown)
|
||||
|
||||
- Clean, readable structure
|
||||
- Code syntax highlighting
|
||||
- Table support
|
||||
- Cross-reference links
|
||||
|
||||
### Metadata Inclusion
|
||||
|
||||
- JSON schemas for automated processing
|
||||
- OpenAPI specifications where applicable
|
||||
- Machine-readable type definitions
|
||||
@@ -164,4 +178,4 @@ You are a reference documentation specialist focused on creating comprehensive,
|
||||
- Version everything
|
||||
- Make search terms explicit
|
||||
|
||||
Remember: Your goal is to create reference documentation that answers every possible question about the system, organized so developers can find answers in seconds, not minutes.
|
||||
Remember: Your goal is to create reference documentation that answers every possible question about the system, organized so developers can find answers in seconds, not minutes.
|
||||
|
||||
@@ -34,12 +34,14 @@ You are a tutorial engineering specialist who transforms complex technical conce
|
||||
## Tutorial Structure
|
||||
|
||||
### Opening Section
|
||||
|
||||
- **What You'll Learn**: Clear learning objectives
|
||||
- **Prerequisites**: Required knowledge and setup
|
||||
- **Time Estimate**: Realistic completion time
|
||||
- **Final Result**: Preview of what they'll build
|
||||
|
||||
### Progressive Sections
|
||||
|
||||
1. **Concept Introduction**: Theory with real-world analogies
|
||||
2. **Minimal Example**: Simplest working implementation
|
||||
3. **Guided Practice**: Step-by-step walkthrough
|
||||
@@ -48,6 +50,7 @@ You are a tutorial engineering specialist who transforms complex technical conce
|
||||
6. **Troubleshooting**: Common errors and solutions
|
||||
|
||||
### Closing Section
|
||||
|
||||
- **Summary**: Key concepts reinforced
|
||||
- **Next Steps**: Where to go from here
|
||||
- **Additional Resources**: Deeper learning paths
|
||||
@@ -63,18 +66,21 @@ You are a tutorial engineering specialist who transforms complex technical conce
|
||||
## Content Elements
|
||||
|
||||
### Code Examples
|
||||
|
||||
- Start with complete, runnable examples
|
||||
- Use meaningful variable and function names
|
||||
- Include inline comments for clarity
|
||||
- Show both correct and incorrect approaches
|
||||
|
||||
### Explanations
|
||||
|
||||
- Use analogies to familiar concepts
|
||||
- Provide the "why" behind each step
|
||||
- Connect to real-world use cases
|
||||
- Anticipate and answer questions
|
||||
|
||||
### Visual Aids
|
||||
|
||||
- Diagrams showing data flow
|
||||
- Before/after comparisons
|
||||
- Decision trees for choosing approaches
|
||||
@@ -108,6 +114,7 @@ You are a tutorial engineering specialist who transforms complex technical conce
|
||||
## Output Format
|
||||
|
||||
Generate tutorials in Markdown with:
|
||||
|
||||
- Clear section numbering
|
||||
- Code blocks with expected output
|
||||
- Info boxes for tips and warnings
|
||||
@@ -115,4 +122,4 @@ Generate tutorials in Markdown with:
|
||||
- Collapsible sections for solutions
|
||||
- Links to working code repositories
|
||||
|
||||
Remember: Your goal is to create tutorials that transform learners from confused to confident, ensuring they not only understand the code but can apply concepts independently.
|
||||
Remember: Your goal is to create tutorials that transform learners from confused to confident, ensuring they not only understand the code but can apply concepts independently.
|
||||
|
||||
@@ -3,14 +3,17 @@
|
||||
You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user guides, and technical references using AI-powered analysis and industry best practices.
|
||||
|
||||
## Context
|
||||
|
||||
The user needs automated documentation generation that extracts information from code, creates clear explanations, and maintains consistency across documentation types. Focus on creating living documentation that stays synchronized with code.
|
||||
|
||||
## Requirements
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
## How to Use This Tool
|
||||
|
||||
This tool provides both **concise instructions** (what to create) and **detailed reference examples** (how to create it). Structure:
|
||||
|
||||
- **Instructions**: High-level guidance and documentation types to generate
|
||||
- **Reference Examples**: Complete implementation patterns to adapt and use as templates
|
||||
|
||||
@@ -19,30 +22,35 @@ This tool provides both **concise instructions** (what to create) and **detailed
|
||||
Generate comprehensive documentation by analyzing the codebase and creating the following artifacts:
|
||||
|
||||
### 1. **API Documentation**
|
||||
|
||||
- Extract endpoint definitions, parameters, and responses from code
|
||||
- Generate OpenAPI/Swagger specifications
|
||||
- Create interactive API documentation (Swagger UI, Redoc)
|
||||
- Include authentication, rate limiting, and error handling details
|
||||
|
||||
### 2. **Architecture Documentation**
|
||||
|
||||
- Create system architecture diagrams (Mermaid, PlantUML)
|
||||
- Document component relationships and data flows
|
||||
- Explain service dependencies and communication patterns
|
||||
- Include scalability and reliability considerations
|
||||
|
||||
### 3. **Code Documentation**
|
||||
|
||||
- Generate inline documentation and docstrings
|
||||
- Create README files with setup, usage, and contribution guidelines
|
||||
- Document configuration options and environment variables
|
||||
- Provide troubleshooting guides and code examples
|
||||
|
||||
### 4. **User Documentation**
|
||||
|
||||
- Write step-by-step user guides
|
||||
- Create getting started tutorials
|
||||
- Document common workflows and use cases
|
||||
- Include accessibility and localization notes
|
||||
|
||||
### 5. **Documentation Automation**
|
||||
|
||||
- Configure CI/CD pipelines for automatic doc generation
|
||||
- Set up documentation linting and validation
|
||||
- Implement documentation coverage checks
|
||||
@@ -51,6 +59,7 @@ Generate comprehensive documentation by analyzing the codebase and creating the
|
||||
### Quality Standards
|
||||
|
||||
Ensure all generated documentation:
|
||||
|
||||
- Is accurate and synchronized with current code
|
||||
- Uses consistent terminology and formatting
|
||||
- Includes practical examples and use cases
|
||||
@@ -62,6 +71,7 @@ Ensure all generated documentation:
|
||||
### Example 1: Code Analysis for Documentation
|
||||
|
||||
**API Documentation Extraction**
|
||||
|
||||
```python
|
||||
import ast
|
||||
from typing import Dict, List
|
||||
@@ -103,6 +113,7 @@ class APIDocExtractor:
|
||||
```
|
||||
|
||||
**Schema Extraction**
|
||||
|
||||
```python
|
||||
def extract_pydantic_schemas(file_path):
|
||||
"""Extract Pydantic model definitions for API documentation"""
|
||||
@@ -135,6 +146,7 @@ def extract_pydantic_schemas(file_path):
|
||||
### Example 2: OpenAPI Specification Generation
|
||||
|
||||
**OpenAPI Template**
|
||||
|
||||
```yaml
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
@@ -173,7 +185,7 @@ paths:
|
||||
default: 20
|
||||
maximum: 100
|
||||
responses:
|
||||
'200':
|
||||
"200":
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
@@ -183,11 +195,11 @@ paths:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/User'
|
||||
$ref: "#/components/schemas/User"
|
||||
pagination:
|
||||
$ref: '#/components/schemas/Pagination'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
$ref: "#/components/schemas/Pagination"
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
|
||||
components:
|
||||
schemas:
|
||||
@@ -213,6 +225,7 @@ components:
|
||||
### Example 3: Architecture Diagrams
|
||||
|
||||
**System Architecture (Mermaid)**
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Frontend"
|
||||
@@ -249,12 +262,14 @@ graph TB
|
||||
```
|
||||
|
||||
**Component Documentation**
|
||||
```markdown
|
||||
|
||||
````markdown
|
||||
## User Service
|
||||
|
||||
**Purpose**: Manages user accounts, authentication, and profiles
|
||||
|
||||
**Technology Stack**:
|
||||
|
||||
- Language: Python 3.11
|
||||
- Framework: FastAPI
|
||||
- Database: PostgreSQL
|
||||
@@ -262,12 +277,14 @@ graph TB
|
||||
- Authentication: JWT
|
||||
|
||||
**API Endpoints**:
|
||||
|
||||
- `POST /users` - Create new user
|
||||
- `GET /users/{id}` - Get user details
|
||||
- `PUT /users/{id}` - Update user
|
||||
- `POST /auth/login` - User login
|
||||
|
||||
**Configuration**:
|
||||
|
||||
```yaml
|
||||
user_service:
|
||||
port: 8001
|
||||
@@ -278,7 +295,9 @@ user_service:
|
||||
secret: ${JWT_SECRET}
|
||||
expiry: 3600
|
||||
```
|
||||
```
|
||||
````
|
||||
|
||||
````
|
||||
|
||||
### Example 4: README Generation
|
||||
|
||||
@@ -306,7 +325,7 @@ ${FEATURES_LIST}
|
||||
|
||||
```bash
|
||||
pip install ${PACKAGE_NAME}
|
||||
```
|
||||
````
|
||||
|
||||
### From source
|
||||
|
||||
@@ -326,11 +345,11 @@ ${QUICK_START_CODE}
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default | Required |
|
||||
|----------|-------------|---------|----------|
|
||||
| DATABASE_URL | PostgreSQL connection string | - | Yes |
|
||||
| REDIS_URL | Redis connection string | - | Yes |
|
||||
| SECRET_KEY | Application secret key | - | Yes |
|
||||
| Variable | Description | Default | Required |
|
||||
| ------------ | ---------------------------- | ------- | -------- |
|
||||
| DATABASE_URL | PostgreSQL connection string | - | Yes |
|
||||
| REDIS_URL | Redis connection string | - | Yes |
|
||||
| SECRET_KEY | Application secret key | - | Yes |
|
||||
|
||||
## Development
|
||||
|
||||
@@ -372,7 +391,8 @@ pytest --cov=your_package
|
||||
## License
|
||||
|
||||
This project is licensed under the ${LICENSE} License - see the [LICENSE](LICENSE) file for details.
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
### Example 5: Function Documentation Generator
|
||||
|
||||
@@ -415,7 +435,7 @@ def {func.__name__}({", ".join(params)}){return_type}:
|
||||
"""
|
||||
'''
|
||||
return doc_template
|
||||
```
|
||||
````
|
||||
|
||||
### Example 6: User Guide Template
|
||||
|
||||
@@ -435,7 +455,6 @@ def {func.__name__}({", ".join(params)}){return_type}:
|
||||
You'll find the "Create New" button in the top right corner.
|
||||
|
||||
3. **Fill in the Details**
|
||||
|
||||
- **Name**: Enter a descriptive name
|
||||
- **Description**: Add optional details
|
||||
- **Settings**: Configure as needed
|
||||
@@ -463,43 +482,48 @@ def {func.__name__}({", ".join(params)}){return_type}:
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
| Error | Meaning | Solution |
|
||||
|-------|---------|----------|
|
||||
| "Name required" | The name field is empty | Enter a name |
|
||||
| "Permission denied" | You don't have access | Contact admin |
|
||||
| "Server error" | Technical issue | Try again later |
|
||||
| Error | Meaning | Solution |
|
||||
| ------------------- | ----------------------- | --------------- |
|
||||
| "Name required" | The name field is empty | Enter a name |
|
||||
| "Permission denied" | You don't have access | Contact admin |
|
||||
| "Server error" | Technical issue | Try again later |
|
||||
```
|
||||
|
||||
### Example 7: Interactive API Playground
|
||||
|
||||
**Swagger UI Setup**
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<head>
|
||||
<title>API Documentation</title>
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/swagger-ui.css">
|
||||
</head>
|
||||
<body>
|
||||
<link
|
||||
rel="stylesheet"
|
||||
href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/swagger-ui.css"
|
||||
/>
|
||||
</head>
|
||||
<body>
|
||||
<div id="swagger-ui"></div>
|
||||
|
||||
<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/swagger-ui-bundle.js"></script>
|
||||
<script>
|
||||
window.onload = function() {
|
||||
SwaggerUIBundle({
|
||||
url: "/api/openapi.json",
|
||||
dom_id: '#swagger-ui',
|
||||
deepLinking: true,
|
||||
presets: [SwaggerUIBundle.presets.apis],
|
||||
layout: "StandaloneLayout"
|
||||
});
|
||||
}
|
||||
window.onload = function () {
|
||||
SwaggerUIBundle({
|
||||
url: "/api/openapi.json",
|
||||
dom_id: "#swagger-ui",
|
||||
deepLinking: true,
|
||||
presets: [SwaggerUIBundle.presets.apis],
|
||||
layout: "StandaloneLayout",
|
||||
});
|
||||
};
|
||||
</script>
|
||||
</body>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
**Code Examples Generator**
|
||||
|
||||
```python
|
||||
def generate_code_examples(endpoint):
|
||||
"""Generate code examples for API endpoints in multiple languages"""
|
||||
@@ -539,6 +563,7 @@ curl -X {endpoint['method']} https://api.example.com{endpoint['path']} \\
|
||||
### Example 8: Documentation CI/CD
|
||||
|
||||
**GitHub Actions Workflow**
|
||||
|
||||
```yaml
|
||||
name: Generate Documentation
|
||||
|
||||
@@ -546,39 +571,39 @@ on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'src/**'
|
||||
- 'api/**'
|
||||
- "src/**"
|
||||
- "api/**"
|
||||
|
||||
jobs:
|
||||
generate-docs:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.11'
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: "3.11"
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install -r requirements-docs.txt
|
||||
npm install -g @redocly/cli
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install -r requirements-docs.txt
|
||||
npm install -g @redocly/cli
|
||||
|
||||
- name: Generate API documentation
|
||||
run: |
|
||||
python scripts/generate_openapi.py > docs/api/openapi.json
|
||||
redocly build-docs docs/api/openapi.json -o docs/api/index.html
|
||||
- name: Generate API documentation
|
||||
run: |
|
||||
python scripts/generate_openapi.py > docs/api/openapi.json
|
||||
redocly build-docs docs/api/openapi.json -o docs/api/index.html
|
||||
|
||||
- name: Generate code documentation
|
||||
run: sphinx-build -b html docs/source docs/build
|
||||
- name: Generate code documentation
|
||||
run: sphinx-build -b html docs/source docs/build
|
||||
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./docs/build
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./docs/build
|
||||
```
|
||||
|
||||
### Example 9: Documentation Coverage Validation
|
||||
|
||||
@@ -21,19 +21,20 @@ Comprehensive patterns for creating, maintaining, and managing Architecture Deci
|
||||
### 1. What is an ADR?
|
||||
|
||||
An Architecture Decision Record captures:
|
||||
|
||||
- **Context**: Why we needed to make a decision
|
||||
- **Decision**: What we decided
|
||||
- **Consequences**: What happens as a result
|
||||
|
||||
### 2. When to Write an ADR
|
||||
|
||||
| Write ADR | Skip ADR |
|
||||
|-----------|----------|
|
||||
| New framework adoption | Minor version upgrades |
|
||||
| Database technology choice | Bug fixes |
|
||||
| API design patterns | Implementation details |
|
||||
| Security architecture | Routine maintenance |
|
||||
| Integration patterns | Configuration changes |
|
||||
| Write ADR | Skip ADR |
|
||||
| -------------------------- | ---------------------- |
|
||||
| New framework adoption | Minor version upgrades |
|
||||
| Database technology choice | Bug fixes |
|
||||
| API design patterns | Implementation details |
|
||||
| Security architecture | Routine maintenance |
|
||||
| Integration patterns | Configuration changes |
|
||||
|
||||
### 3. ADR Lifecycle
|
||||
|
||||
@@ -58,6 +59,7 @@ Accepted
|
||||
|
||||
We need to select a primary database for our new e-commerce platform. The system
|
||||
will handle:
|
||||
|
||||
- ~10,000 concurrent users
|
||||
- Complex product catalog with hierarchical categories
|
||||
- Transaction processing for orders and payments
|
||||
@@ -69,25 +71,28 @@ compliance for financial transactions.
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
* **Must have ACID compliance** for payment processing
|
||||
* **Must support complex queries** for reporting
|
||||
* **Should support full-text search** to reduce infrastructure complexity
|
||||
* **Should have good JSON support** for flexible product attributes
|
||||
* **Team familiarity** reduces onboarding time
|
||||
- **Must have ACID compliance** for payment processing
|
||||
- **Must support complex queries** for reporting
|
||||
- **Should support full-text search** to reduce infrastructure complexity
|
||||
- **Should have good JSON support** for flexible product attributes
|
||||
- **Team familiarity** reduces onboarding time
|
||||
|
||||
## Considered Options
|
||||
|
||||
### Option 1: PostgreSQL
|
||||
|
||||
- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text
|
||||
search, PostGIS for geospatial, team has experience
|
||||
- **Cons**: Slightly more complex replication setup than MySQL
|
||||
|
||||
### Option 2: MySQL
|
||||
|
||||
- **Pros**: Very familiar to team, simple replication, large community
|
||||
- **Cons**: Weaker JSON support, no built-in full-text search (need
|
||||
Elasticsearch), no geospatial without extensions
|
||||
|
||||
### Option 3: MongoDB
|
||||
|
||||
- **Pros**: Flexible schema, native JSON, horizontal scaling
|
||||
- **Cons**: No ACID for multi-document transactions (at decision time),
|
||||
team has limited experience, requires schema design discipline
|
||||
@@ -99,6 +104,7 @@ We will use **PostgreSQL 15** as our primary database.
|
||||
## Rationale
|
||||
|
||||
PostgreSQL provides the best balance of:
|
||||
|
||||
1. **ACID compliance** essential for e-commerce transactions
|
||||
2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce
|
||||
infrastructure complexity
|
||||
@@ -111,17 +117,20 @@ additional services (no separate Elasticsearch needed).
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Single database handles transactions, search, and geospatial queries
|
||||
- Reduced operational complexity (fewer services to manage)
|
||||
- Strong consistency guarantees for financial data
|
||||
- Team can leverage existing SQL expertise
|
||||
|
||||
### Negative
|
||||
|
||||
- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
|
||||
- Vertical scaling limits may require read replicas sooner
|
||||
- Some team members need PostgreSQL-specific training
|
||||
|
||||
### Risks
|
||||
|
||||
- Full-text search may not scale as well as dedicated search engines
|
||||
- Mitigation: Design for potential Elasticsearch addition if needed
|
||||
|
||||
@@ -200,6 +209,7 @@ Accepted (Supersedes ADR-0003)
|
||||
|
||||
ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility
|
||||
needs. Since then:
|
||||
|
||||
- MongoDB's multi-document transactions remain problematic for our use case
|
||||
- Our schema has stabilized and rarely changes
|
||||
- We now have PostgreSQL expertise from other services
|
||||
@@ -219,11 +229,13 @@ Deprecate MongoDB and migrate user profiles to PostgreSQL.
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Single database technology reduces operational complexity
|
||||
- ACID transactions for user data
|
||||
- Team can focus PostgreSQL expertise
|
||||
|
||||
### Negative
|
||||
|
||||
- Migration effort (~4 weeks)
|
||||
- Risk of data issues during migration
|
||||
- Lose some schema flexibility
|
||||
@@ -231,6 +243,7 @@ Deprecate MongoDB and migrate user profiles to PostgreSQL.
|
||||
## Lessons Learned
|
||||
|
||||
Document from ADR-0003 experience:
|
||||
|
||||
- Schema flexibility benefits were overestimated
|
||||
- Operational cost of multiple databases was underestimated
|
||||
- Consider long-term maintenance in technology decisions
|
||||
@@ -249,6 +262,7 @@ improve auditability, enable temporal queries, and support business analytics.
|
||||
## Motivation
|
||||
|
||||
Current challenges:
|
||||
|
||||
1. Audit requirements need complete order history
|
||||
2. "What was the order state at time X?" queries are impossible
|
||||
3. Analytics team needs event stream for real-time dashboards
|
||||
@@ -257,13 +271,14 @@ Current challenges:
|
||||
## Detailed Design
|
||||
|
||||
### Event Store
|
||||
|
||||
```
|
||||
|
||||
OrderCreated { orderId, customerId, items[], timestamp }
|
||||
OrderItemAdded { orderId, item, timestamp }
|
||||
OrderItemRemoved { orderId, itemId, timestamp }
|
||||
PaymentReceived { orderId, amount, paymentId, timestamp }
|
||||
OrderShipped { orderId, trackingNumber, timestamp }
|
||||
|
||||
```
|
||||
|
||||
### Projections
|
||||
@@ -333,12 +348,12 @@ This directory contains Architecture Decision Records (ADRs) for [Project Name].
|
||||
|
||||
## Index
|
||||
|
||||
| ADR | Title | Status | Date |
|
||||
|-----|-------|--------|------|
|
||||
| [0001](0001-use-postgresql.md) | Use PostgreSQL as Primary Database | Accepted | 2024-01-10 |
|
||||
| [0002](0002-caching-strategy.md) | Caching Strategy with Redis | Accepted | 2024-01-12 |
|
||||
| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles | Deprecated | 2023-06-15 |
|
||||
| [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 |
|
||||
| ADR | Title | Status | Date |
|
||||
| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
|
||||
| [0001](0001-use-postgresql.md) | Use PostgreSQL as Primary Database | Accepted | 2024-01-10 |
|
||||
| [0002](0002-caching-strategy.md) | Caching Strategy with Redis | Accepted | 2024-01-12 |
|
||||
| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles | Deprecated | 2023-06-15 |
|
||||
| [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 |
|
||||
|
||||
## Creating a New ADR
|
||||
|
||||
@@ -384,6 +399,7 @@ adr link 2 "Complements" 1 "Is complemented by"
|
||||
## ADR Review Checklist
|
||||
|
||||
### Before Submission
|
||||
|
||||
- [ ] Context clearly explains the problem
|
||||
- [ ] All viable options considered
|
||||
- [ ] Pros/cons balanced and honest
|
||||
@@ -391,6 +407,7 @@ adr link 2 "Complements" 1 "Is complemented by"
|
||||
- [ ] Related ADRs linked
|
||||
|
||||
### During Review
|
||||
|
||||
- [ ] At least 2 senior engineers reviewed
|
||||
- [ ] Affected teams consulted
|
||||
- [ ] Security implications considered
|
||||
@@ -398,6 +415,7 @@ adr link 2 "Complements" 1 "Is complemented by"
|
||||
- [ ] Reversibility assessed
|
||||
|
||||
### After Acceptance
|
||||
|
||||
- [ ] ADR index updated
|
||||
- [ ] Team notified
|
||||
- [ ] Implementation tickets created
|
||||
@@ -407,6 +425,7 @@ adr link 2 "Complements" 1 "Is complemented by"
|
||||
## Best Practices
|
||||
|
||||
### Do's
|
||||
|
||||
- **Write ADRs early** - Before implementation starts
|
||||
- **Keep them short** - 1-2 pages maximum
|
||||
- **Be honest about trade-offs** - Include real cons
|
||||
@@ -414,6 +433,7 @@ adr link 2 "Complements" 1 "Is complemented by"
|
||||
- **Update status** - Deprecate when superseded
|
||||
|
||||
### Don'ts
|
||||
|
||||
- **Don't change accepted ADRs** - Write new ones to supersede
|
||||
- **Don't skip context** - Future readers need background
|
||||
- **Don't hide failures** - Rejected decisions are valuable
|
||||
|
||||
@@ -31,27 +31,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
|
||||
- New feature X
|
||||
|
||||
## [1.2.0] - 2024-01-15
|
||||
|
||||
### Added
|
||||
|
||||
- User profile avatars
|
||||
- Dark mode support
|
||||
|
||||
### Changed
|
||||
|
||||
- Improved loading performance by 40%
|
||||
|
||||
### Deprecated
|
||||
|
||||
- Old authentication API (use v2)
|
||||
|
||||
### Removed
|
||||
|
||||
- Legacy payment gateway
|
||||
|
||||
### Fixed
|
||||
|
||||
- Login timeout issue (#123)
|
||||
|
||||
### Security
|
||||
|
||||
- Updated dependencies for CVE-2024-1234
|
||||
|
||||
[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
|
||||
@@ -68,19 +75,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
| Type | Description | Changelog Section |
|
||||
|------|-------------|-------------------|
|
||||
| `feat` | New feature | Added |
|
||||
| `fix` | Bug fix | Fixed |
|
||||
| `docs` | Documentation | (usually excluded) |
|
||||
| `style` | Formatting | (usually excluded) |
|
||||
| `refactor` | Code restructure | Changed |
|
||||
| `perf` | Performance | Changed |
|
||||
| `test` | Tests | (usually excluded) |
|
||||
| `chore` | Maintenance | (usually excluded) |
|
||||
| `ci` | CI changes | (usually excluded) |
|
||||
| `build` | Build system | (usually excluded) |
|
||||
| `revert` | Revert commit | Removed |
|
||||
| Type | Description | Changelog Section |
|
||||
| ---------- | ---------------- | ------------------ |
|
||||
| `feat` | New feature | Added |
|
||||
| `fix` | Bug fix | Fixed |
|
||||
| `docs` | Documentation | (usually excluded) |
|
||||
| `style` | Formatting | (usually excluded) |
|
||||
| `refactor` | Code restructure | Changed |
|
||||
| `perf` | Performance | Changed |
|
||||
| `test` | Tests | (usually excluded) |
|
||||
| `chore` | Maintenance | (usually excluded) |
|
||||
| `ci` | CI changes | (usually excluded) |
|
||||
| `build` | Build system | (usually excluded) |
|
||||
| `revert` | Revert commit | Removed |
|
||||
|
||||
### 3. Semantic Versioning
|
||||
|
||||
@@ -143,23 +150,24 @@ echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
|
||||
// .versionrc.js
|
||||
module.exports = {
|
||||
types: [
|
||||
{ type: 'feat', section: 'Features' },
|
||||
{ type: 'fix', section: 'Bug Fixes' },
|
||||
{ type: 'perf', section: 'Performance Improvements' },
|
||||
{ type: 'revert', section: 'Reverts' },
|
||||
{ type: 'docs', section: 'Documentation', hidden: true },
|
||||
{ type: 'style', section: 'Styles', hidden: true },
|
||||
{ type: 'chore', section: 'Miscellaneous', hidden: true },
|
||||
{ type: 'refactor', section: 'Code Refactoring', hidden: true },
|
||||
{ type: 'test', section: 'Tests', hidden: true },
|
||||
{ type: 'build', section: 'Build System', hidden: true },
|
||||
{ type: 'ci', section: 'CI/CD', hidden: true },
|
||||
{ type: "feat", section: "Features" },
|
||||
{ type: "fix", section: "Bug Fixes" },
|
||||
{ type: "perf", section: "Performance Improvements" },
|
||||
{ type: "revert", section: "Reverts" },
|
||||
{ type: "docs", section: "Documentation", hidden: true },
|
||||
{ type: "style", section: "Styles", hidden: true },
|
||||
{ type: "chore", section: "Miscellaneous", hidden: true },
|
||||
{ type: "refactor", section: "Code Refactoring", hidden: true },
|
||||
{ type: "test", section: "Tests", hidden: true },
|
||||
{ type: "build", section: "Build System", hidden: true },
|
||||
{ type: "ci", section: "CI/CD", hidden: true },
|
||||
],
|
||||
commitUrlFormat: '{{host}}/{{owner}}/{{repository}}/commit/{{hash}}',
|
||||
compareUrlFormat: '{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}',
|
||||
issueUrlFormat: '{{host}}/{{owner}}/{{repository}}/issues/{{id}}',
|
||||
userUrlFormat: '{{host}}/{{user}}',
|
||||
releaseCommitMessageFormat: 'chore(release): {{currentTag}}',
|
||||
commitUrlFormat: "{{host}}/{{owner}}/{{repository}}/commit/{{hash}}",
|
||||
compareUrlFormat:
|
||||
"{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}",
|
||||
issueUrlFormat: "{{host}}/{{owner}}/{{repository}}/issues/{{id}}",
|
||||
userUrlFormat: "{{host}}/{{user}}",
|
||||
releaseCommitMessageFormat: "chore(release): {{currentTag}}",
|
||||
scripts: {
|
||||
prebump: 'echo "Running prebump"',
|
||||
postbump: 'echo "Running postbump"',
|
||||
@@ -188,36 +196,37 @@ module.exports = {
|
||||
// release.config.js
|
||||
module.exports = {
|
||||
branches: [
|
||||
'main',
|
||||
{ name: 'beta', prerelease: true },
|
||||
{ name: 'alpha', prerelease: true },
|
||||
"main",
|
||||
{ name: "beta", prerelease: true },
|
||||
{ name: "alpha", prerelease: true },
|
||||
],
|
||||
plugins: [
|
||||
'@semantic-release/commit-analyzer',
|
||||
'@semantic-release/release-notes-generator',
|
||||
"@semantic-release/commit-analyzer",
|
||||
"@semantic-release/release-notes-generator",
|
||||
[
|
||||
'@semantic-release/changelog',
|
||||
"@semantic-release/changelog",
|
||||
{
|
||||
changelogFile: 'CHANGELOG.md',
|
||||
changelogFile: "CHANGELOG.md",
|
||||
},
|
||||
],
|
||||
[
|
||||
'@semantic-release/npm',
|
||||
"@semantic-release/npm",
|
||||
{
|
||||
npmPublish: true,
|
||||
},
|
||||
],
|
||||
[
|
||||
'@semantic-release/github',
|
||||
"@semantic-release/github",
|
||||
{
|
||||
assets: ['dist/**/*.js', 'dist/**/*.css'],
|
||||
assets: ["dist/**/*.js", "dist/**/*.css"],
|
||||
},
|
||||
],
|
||||
[
|
||||
'@semantic-release/git',
|
||||
"@semantic-release/git",
|
||||
{
|
||||
assets: ['CHANGELOG.md', 'package.json'],
|
||||
message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
|
||||
assets: ["CHANGELOG.md", "package.json"],
|
||||
message:
|
||||
"chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}",
|
||||
},
|
||||
],
|
||||
],
|
||||
@@ -236,9 +245,9 @@ on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
release_type:
|
||||
description: 'Release type'
|
||||
description: "Release type"
|
||||
required: true
|
||||
default: 'patch'
|
||||
default: "patch"
|
||||
type: choice
|
||||
options:
|
||||
- patch
|
||||
@@ -260,8 +269,8 @@ jobs:
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
node-version: "20"
|
||||
cache: "npm"
|
||||
|
||||
- run: npm ci
|
||||
|
||||
@@ -287,7 +296,7 @@ jobs:
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
node-version: "20"
|
||||
|
||||
- run: npm ci
|
||||
|
||||
@@ -434,29 +443,39 @@ cz check --rev-range HEAD~5..HEAD
|
||||
## What's Changed
|
||||
|
||||
### 🚀 Features
|
||||
|
||||
{{ range .Features }}
|
||||
|
||||
- {{ .Title }} by @{{ .Author }} in #{{ .PR }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
### 🐛 Bug Fixes
|
||||
|
||||
{{ range .Fixes }}
|
||||
|
||||
- {{ .Title }} by @{{ .Author }} in #{{ .PR }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
### 📚 Documentation
|
||||
|
||||
{{ range .Docs }}
|
||||
|
||||
- {{ .Title }} by @{{ .Author }} in #{{ .PR }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
### 🔧 Maintenance
|
||||
|
||||
{{ range .Chores }}
|
||||
|
||||
- {{ .Title }} by @{{ .Author }} in #{{ .PR }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
## New Contributors
|
||||
|
||||
{{ range .NewContributors }}
|
||||
|
||||
- @{{ .Username }} made their first contribution in #{{ .PR }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
**Full Changelog**: https://github.com/owner/repo/compare/v{{ .Previous }}...v{{ .Current }}
|
||||
```
|
||||
@@ -467,33 +486,40 @@ cz check --rev-range HEAD~5..HEAD
|
||||
# Release v2.1.0 - January 15, 2024
|
||||
|
||||
## Summary
|
||||
|
||||
This release introduces dark mode support and improves checkout performance
|
||||
by 40%. It also includes important security updates.
|
||||
|
||||
## Highlights
|
||||
|
||||
### 🌙 Dark Mode
|
||||
|
||||
Users can now switch to dark mode from settings. The preference is
|
||||
automatically saved and synced across devices.
|
||||
|
||||
### ⚡ Performance
|
||||
|
||||
- Checkout flow is 40% faster
|
||||
- Reduced bundle size by 15%
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
None in this release.
|
||||
|
||||
## Upgrade Guide
|
||||
|
||||
No special steps required. Standard deployment process applies.
|
||||
|
||||
## Known Issues
|
||||
|
||||
- Dark mode may flicker on initial load (fix scheduled for v2.1.1)
|
||||
|
||||
## Dependencies Updated
|
||||
| Package | From | To | Reason |
|
||||
|---------|------|-----|--------|
|
||||
| react | 18.2.0 | 18.3.0 | Performance improvements |
|
||||
| lodash | 4.17.20 | 4.17.21 | Security patch |
|
||||
|
||||
| Package | From | To | Reason |
|
||||
| ------- | ------- | ------- | ------------------------ |
|
||||
| react | 18.2.0 | 18.3.0 | Performance improvements |
|
||||
| lodash | 4.17.20 | 4.17.21 | Security patch |
|
||||
```
|
||||
|
||||
## Commit Message Examples
|
||||
@@ -530,6 +556,7 @@ Reviewed-by: @alice
|
||||
## Best Practices
|
||||
|
||||
### Do's
|
||||
|
||||
- **Follow Conventional Commits** - Enables automation
|
||||
- **Write clear messages** - Future you will thank you
|
||||
- **Reference issues** - Link commits to tickets
|
||||
@@ -537,6 +564,7 @@ Reviewed-by: @alice
|
||||
- **Automate releases** - Reduce manual errors
|
||||
|
||||
### Don'ts
|
||||
|
||||
- **Don't mix changes** - One logical change per commit
|
||||
- **Don't skip validation** - Use commitlint
|
||||
- **Don't manual edit** - Generated changelogs only
|
||||
|
||||
@@ -37,11 +37,11 @@ components:
|
||||
|
||||
### 2. Design Approaches
|
||||
|
||||
| Approach | Description | Best For |
|
||||
|----------|-------------|----------|
|
||||
| **Design-First** | Write spec before code | New APIs, contracts |
|
||||
| **Code-First** | Generate spec from code | Existing APIs |
|
||||
| **Hybrid** | Annotate code, generate spec | Evolving APIs |
|
||||
| Approach | Description | Best For |
|
||||
| ---------------- | ---------------------------- | ------------------- |
|
||||
| **Design-First** | Write spec before code | New APIs, contracts |
|
||||
| **Code-First** | Generate spec from code | Existing APIs |
|
||||
| **Hybrid** | Annotate code, generate spec | Evolving APIs |
|
||||
|
||||
## Templates
|
||||
|
||||
@@ -94,13 +94,13 @@ paths:
|
||||
tags:
|
||||
- Users
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/PageParam'
|
||||
- $ref: '#/components/parameters/LimitParam'
|
||||
- $ref: "#/components/parameters/PageParam"
|
||||
- $ref: "#/components/parameters/LimitParam"
|
||||
- name: status
|
||||
in: query
|
||||
description: Filter by user status
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserStatus'
|
||||
$ref: "#/components/schemas/UserStatus"
|
||||
- name: search
|
||||
in: query
|
||||
description: Search by name or email
|
||||
@@ -109,21 +109,21 @@ paths:
|
||||
minLength: 2
|
||||
maxLength: 100
|
||||
responses:
|
||||
'200':
|
||||
"200":
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserListResponse'
|
||||
$ref: "#/components/schemas/UserListResponse"
|
||||
examples:
|
||||
default:
|
||||
$ref: '#/components/examples/UserListExample'
|
||||
'400':
|
||||
$ref: '#/components/responses/BadRequest'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'429':
|
||||
$ref: '#/components/responses/RateLimited'
|
||||
$ref: "#/components/examples/UserListExample"
|
||||
"400":
|
||||
$ref: "#/components/responses/BadRequest"
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
"429":
|
||||
$ref: "#/components/responses/RateLimited"
|
||||
security:
|
||||
- bearerAuth: []
|
||||
|
||||
@@ -138,7 +138,7 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateUserRequest'
|
||||
$ref: "#/components/schemas/CreateUserRequest"
|
||||
examples:
|
||||
standard:
|
||||
summary: Standard user
|
||||
@@ -153,32 +153,32 @@ paths:
|
||||
name: Admin User
|
||||
role: admin
|
||||
responses:
|
||||
'201':
|
||||
"201":
|
||||
description: User created successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
$ref: "#/components/schemas/User"
|
||||
headers:
|
||||
Location:
|
||||
description: URL of created user
|
||||
schema:
|
||||
type: string
|
||||
format: uri
|
||||
'400':
|
||||
$ref: '#/components/responses/BadRequest'
|
||||
'409':
|
||||
"400":
|
||||
$ref: "#/components/responses/BadRequest"
|
||||
"409":
|
||||
description: Email already exists
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
$ref: "#/components/schemas/Error"
|
||||
security:
|
||||
- bearerAuth: []
|
||||
|
||||
/users/{userId}:
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/UserIdParam'
|
||||
- $ref: "#/components/parameters/UserIdParam"
|
||||
|
||||
get:
|
||||
operationId: getUser
|
||||
@@ -186,14 +186,14 @@ paths:
|
||||
tags:
|
||||
- Users
|
||||
responses:
|
||||
'200':
|
||||
"200":
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
$ref: "#/components/schemas/User"
|
||||
"404":
|
||||
$ref: "#/components/responses/NotFound"
|
||||
security:
|
||||
- bearerAuth: []
|
||||
|
||||
@@ -207,18 +207,18 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UpdateUserRequest'
|
||||
$ref: "#/components/schemas/UpdateUserRequest"
|
||||
responses:
|
||||
'200':
|
||||
"200":
|
||||
description: User updated
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
'400':
|
||||
$ref: '#/components/responses/BadRequest'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
$ref: "#/components/schemas/User"
|
||||
"400":
|
||||
$ref: "#/components/responses/BadRequest"
|
||||
"404":
|
||||
$ref: "#/components/responses/NotFound"
|
||||
security:
|
||||
- bearerAuth: []
|
||||
|
||||
@@ -229,10 +229,10 @@ paths:
|
||||
- Users
|
||||
- Admin
|
||||
responses:
|
||||
'204':
|
||||
"204":
|
||||
description: User deleted
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
"404":
|
||||
$ref: "#/components/responses/NotFound"
|
||||
security:
|
||||
- bearerAuth: []
|
||||
- apiKey: []
|
||||
@@ -263,7 +263,7 @@ components:
|
||||
maxLength: 100
|
||||
description: User display name
|
||||
status:
|
||||
$ref: '#/components/schemas/UserStatus'
|
||||
$ref: "#/components/schemas/UserStatus"
|
||||
role:
|
||||
type: string
|
||||
enum: [user, moderator, admin]
|
||||
@@ -320,7 +320,7 @@ components:
|
||||
minLength: 1
|
||||
maxLength: 100
|
||||
status:
|
||||
$ref: '#/components/schemas/UserStatus'
|
||||
$ref: "#/components/schemas/UserStatus"
|
||||
role:
|
||||
type: string
|
||||
enum: [user, moderator, admin]
|
||||
@@ -337,9 +337,9 @@ components:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/User'
|
||||
$ref: "#/components/schemas/User"
|
||||
pagination:
|
||||
$ref: '#/components/schemas/Pagination'
|
||||
$ref: "#/components/schemas/Pagination"
|
||||
|
||||
Pagination:
|
||||
type: object
|
||||
@@ -427,7 +427,7 @@ components:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
$ref: "#/components/schemas/Error"
|
||||
example:
|
||||
code: VALIDATION_ERROR
|
||||
message: Invalid request parameters
|
||||
@@ -440,7 +440,7 @@ components:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
$ref: "#/components/schemas/Error"
|
||||
example:
|
||||
code: UNAUTHORIZED
|
||||
message: Authentication required
|
||||
@@ -450,7 +450,7 @@ components:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
$ref: "#/components/schemas/Error"
|
||||
example:
|
||||
code: NOT_FOUND
|
||||
message: User not found
|
||||
@@ -460,7 +460,7 @@ components:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
$ref: "#/components/schemas/Error"
|
||||
headers:
|
||||
Retry-After:
|
||||
description: Seconds until rate limit resets
|
||||
@@ -826,7 +826,7 @@ export class UsersController extends Controller {
|
||||
@Query() page: number = 1,
|
||||
@Query() limit: number = 20,
|
||||
@Query() status?: UserStatus,
|
||||
@Query() search?: string
|
||||
@Query() search?: string,
|
||||
): Promise<UserListResponse> {
|
||||
// Implementation
|
||||
throw new Error("Not implemented");
|
||||
@@ -840,9 +840,7 @@ export class UsersController extends Controller {
|
||||
@SuccessResponse(201, "Created")
|
||||
@Response<ErrorResponse>(400, "Invalid request")
|
||||
@Response<ErrorResponse>(409, "Email already exists")
|
||||
public async createUser(
|
||||
@Body() body: CreateUserRequest
|
||||
): Promise<User> {
|
||||
public async createUser(@Body() body: CreateUserRequest): Promise<User> {
|
||||
this.setStatus(201);
|
||||
throw new Error("Not implemented");
|
||||
}
|
||||
@@ -854,9 +852,7 @@ export class UsersController extends Controller {
|
||||
@Get("{userId}")
|
||||
@Security("bearerAuth")
|
||||
@Response<ErrorResponse>(404, "User not found")
|
||||
public async getUser(
|
||||
@Path() userId: string
|
||||
): Promise<User> {
|
||||
public async getUser(@Path() userId: string): Promise<User> {
|
||||
throw new Error("Not implemented");
|
||||
}
|
||||
|
||||
@@ -870,7 +866,7 @@ export class UsersController extends Controller {
|
||||
@Response<ErrorResponse>(404, "User not found")
|
||||
public async updateUser(
|
||||
@Path() userId: string,
|
||||
@Body() body: UpdateUserRequest
|
||||
@Body() body: UpdateUserRequest,
|
||||
): Promise<User> {
|
||||
throw new Error("Not implemented");
|
||||
}
|
||||
@@ -884,9 +880,7 @@ export class UsersController extends Controller {
|
||||
@Security("bearerAuth")
|
||||
@SuccessResponse(204, "Deleted")
|
||||
@Response<ErrorResponse>(404, "User not found")
|
||||
public async deleteUser(
|
||||
@Path() userId: string
|
||||
): Promise<void> {
|
||||
public async deleteUser(@Path() userId: string): Promise<void> {
|
||||
this.setStatus(204);
|
||||
}
|
||||
}
|
||||
@@ -1007,6 +1001,7 @@ openapi-generator-cli generate \
|
||||
## Best Practices
|
||||
|
||||
### Do's
|
||||
|
||||
- **Use $ref** - Reuse schemas, parameters, responses
|
||||
- **Add examples** - Real-world values help consumers
|
||||
- **Document errors** - All possible error codes
|
||||
@@ -1014,6 +1009,7 @@ openapi-generator-cli generate \
|
||||
- **Use semantic versioning** - For spec changes
|
||||
|
||||
### Don'ts
|
||||
|
||||
- **Don't use generic descriptions** - Be specific
|
||||
- **Don't skip security** - Define all schemes
|
||||
- **Don't forget nullable** - Be explicit about null
|
||||
|
||||
Reference in New Issue
Block a user