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:
@@ -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