feat(bmm): add API design workflow with OpenAPI 3.0 support
- Add workflow.yaml for contract-first API design - Add instructions.md with detailed design process - Add openapi.template.yaml as starting template - Add api-checklist.md for design validation
This commit is contained in:
Ibrahim Elsahafy
parent
4284f80a9a
commit
8a3ba98f16
|
|
@ -0,0 +1,117 @@
|
||||||
|
# API Design Checklist
|
||||||
|
|
||||||
|
## Resource Design
|
||||||
|
- [ ] Resources use plural nouns (users, orders, products)
|
||||||
|
- [ ] Resource names are lowercase with hyphens (user-profiles)
|
||||||
|
- [ ] Relationships expressed via nesting or links
|
||||||
|
- [ ] No verbs in resource paths (use HTTP methods instead)
|
||||||
|
|
||||||
|
## HTTP Methods
|
||||||
|
- [ ] GET for reading (no side effects)
|
||||||
|
- [ ] POST for creating new resources
|
||||||
|
- [ ] PUT for full resource replacement
|
||||||
|
- [ ] PATCH for partial updates
|
||||||
|
- [ ] DELETE for removing resources
|
||||||
|
- [ ] HEAD for metadata requests (if needed)
|
||||||
|
- [ ] OPTIONS for CORS preflight (automatic)
|
||||||
|
|
||||||
|
## Status Codes
|
||||||
|
- [ ] 200 OK for successful GET/PUT/PATCH
|
||||||
|
- [ ] 201 Created for successful POST
|
||||||
|
- [ ] 204 No Content for successful DELETE
|
||||||
|
- [ ] 400 Bad Request for malformed requests
|
||||||
|
- [ ] 401 Unauthorized for missing/invalid auth
|
||||||
|
- [ ] 403 Forbidden for insufficient permissions
|
||||||
|
- [ ] 404 Not Found for missing resources
|
||||||
|
- [ ] 409 Conflict for state conflicts
|
||||||
|
- [ ] 422 Unprocessable Entity for validation errors
|
||||||
|
- [ ] 429 Too Many Requests for rate limiting
|
||||||
|
- [ ] 500 Internal Server Error (avoid exposing details)
|
||||||
|
|
||||||
|
## Request Design
|
||||||
|
- [ ] Content-Type headers required for POST/PUT/PATCH
|
||||||
|
- [ ] Accept headers for content negotiation
|
||||||
|
- [ ] Query parameters for filtering/sorting/pagination
|
||||||
|
- [ ] Path parameters for resource identifiers
|
||||||
|
- [ ] Request body validation documented
|
||||||
|
|
||||||
|
## Response Design
|
||||||
|
- [ ] Consistent envelope structure (data, meta, links, error)
|
||||||
|
- [ ] Timestamps in ISO 8601 format
|
||||||
|
- [ ] IDs as strings (UUIDs recommended)
|
||||||
|
- [ ] Pagination for list endpoints
|
||||||
|
- [ ] HATEOAS links where appropriate
|
||||||
|
|
||||||
|
## Pagination
|
||||||
|
- [ ] Page-based or cursor-based pagination
|
||||||
|
- [ ] Default and maximum limits defined
|
||||||
|
- [ ] Total count available
|
||||||
|
- [ ] Navigation links included
|
||||||
|
|
||||||
|
## Filtering & Sorting
|
||||||
|
- [ ] Filter syntax documented
|
||||||
|
- [ ] Sortable fields specified
|
||||||
|
- [ ] Default sort order defined
|
||||||
|
- [ ] Multiple sort fields supported
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
- [ ] Auth method documented (Bearer, API Key, OAuth2)
|
||||||
|
- [ ] Token format specified (JWT structure)
|
||||||
|
- [ ] Token expiration documented
|
||||||
|
- [ ] Refresh token flow if applicable
|
||||||
|
|
||||||
|
## Authorization
|
||||||
|
- [ ] Per-endpoint permissions documented
|
||||||
|
- [ ] Role-based access defined
|
||||||
|
- [ ] Resource ownership rules clear
|
||||||
|
|
||||||
|
## Versioning
|
||||||
|
- [ ] Versioning strategy chosen (URL, header, parameter)
|
||||||
|
- [ ] Major version in URL (/v1/, /v2/)
|
||||||
|
- [ ] Deprecation policy documented
|
||||||
|
- [ ] Breaking changes defined
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
- [ ] Error response format consistent
|
||||||
|
- [ ] Error codes meaningful and documented
|
||||||
|
- [ ] Validation errors include field details
|
||||||
|
- [ ] No sensitive info in error messages
|
||||||
|
|
||||||
|
## Security
|
||||||
|
- [ ] HTTPS required
|
||||||
|
- [ ] Rate limiting implemented
|
||||||
|
- [ ] CORS properly configured
|
||||||
|
- [ ] Input validation on all fields
|
||||||
|
- [ ] SQL injection prevention
|
||||||
|
- [ ] No sensitive data in URLs
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
- [ ] OpenAPI 3.0+ specification complete
|
||||||
|
- [ ] All endpoints documented
|
||||||
|
- [ ] Request/response examples provided
|
||||||
|
- [ ] Authentication documented
|
||||||
|
- [ ] Error codes listed
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
- [ ] Mock server available
|
||||||
|
- [ ] Example requests for each endpoint
|
||||||
|
- [ ] Postman/Insomnia collection exported
|
||||||
|
- [ ] SDK generation tested
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Validation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Validate OpenAPI spec
|
||||||
|
npx @stoplight/spectral-cli lint api-spec.yaml
|
||||||
|
|
||||||
|
# Alternative validation
|
||||||
|
npx swagger-cli validate api-spec.yaml
|
||||||
|
|
||||||
|
# Generate types (TypeScript)
|
||||||
|
npx openapi-typescript api-spec.yaml -o types.d.ts
|
||||||
|
|
||||||
|
# Start mock server
|
||||||
|
npx @stoplight/prism-cli mock api-spec.yaml
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,309 @@
|
||||||
|
# API Design Workflow Instructions
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Design APIs using a contract-first approach. This workflow produces OpenAPI 3.0+ specifications, mock server configurations, and client SDK generation guidance.
|
||||||
|
|
||||||
|
## Workflow Steps
|
||||||
|
|
||||||
|
### Step 1: Context Loading
|
||||||
|
|
||||||
|
**Load existing documentation:**
|
||||||
|
1. Load PRD for feature requirements
|
||||||
|
2. Load Architecture document for system design
|
||||||
|
3. Load project-context.md for coding standards
|
||||||
|
4. Identify existing API patterns (if any)
|
||||||
|
|
||||||
|
### Step 2: API Style Selection
|
||||||
|
|
||||||
|
**Ask user for API style:**
|
||||||
|
```
|
||||||
|
API Style Selection
|
||||||
|
|
||||||
|
Available styles:
|
||||||
|
1. [rest] RESTful API (OpenAPI 3.0+)
|
||||||
|
2. [graphql] GraphQL Schema
|
||||||
|
3. [grpc] gRPC/Protocol Buffers
|
||||||
|
4. [websocket] WebSocket Event Schema
|
||||||
|
|
||||||
|
Select style [1-4]:
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Resource Identification
|
||||||
|
|
||||||
|
**For REST APIs, identify resources:**
|
||||||
|
1. Extract nouns from PRD (users, orders, products, etc.)
|
||||||
|
2. Map to REST resources
|
||||||
|
3. Identify relationships (1:1, 1:N, N:N)
|
||||||
|
4. Determine resource hierarchy
|
||||||
|
|
||||||
|
**Questions to ask:**
|
||||||
|
- What are the main entities in this system?
|
||||||
|
- How do entities relate to each other?
|
||||||
|
- What operations are needed for each entity?
|
||||||
|
- Are there any batch operations required?
|
||||||
|
|
||||||
|
### Step 4: Endpoint Design
|
||||||
|
|
||||||
|
**For each resource, design endpoints:**
|
||||||
|
|
||||||
|
| Operation | Method | Path Pattern | Example |
|
||||||
|
|-----------|--------|--------------|---------|
|
||||||
|
| List | GET | /resources | GET /users |
|
||||||
|
| Create | POST | /resources | POST /users |
|
||||||
|
| Read | GET | /resources/{id} | GET /users/123 |
|
||||||
|
| Update | PUT/PATCH | /resources/{id} | PATCH /users/123 |
|
||||||
|
| Delete | DELETE | /resources/{id} | DELETE /users/123 |
|
||||||
|
| Nested | GET | /resources/{id}/subs | GET /users/123/orders |
|
||||||
|
|
||||||
|
**Naming conventions:**
|
||||||
|
- Use plural nouns for resources
|
||||||
|
- Use kebab-case for multi-word resources
|
||||||
|
- Use path parameters for identifiers
|
||||||
|
- Use query parameters for filtering/pagination
|
||||||
|
|
||||||
|
### Step 5: Request/Response Design
|
||||||
|
|
||||||
|
**For each endpoint, define:**
|
||||||
|
|
||||||
|
1. **Request body schema** (POST/PUT/PATCH)
|
||||||
|
- Required vs optional fields
|
||||||
|
- Data types and formats
|
||||||
|
- Validation rules (min/max, pattern, enum)
|
||||||
|
|
||||||
|
2. **Response schema**
|
||||||
|
- Success response structure
|
||||||
|
- Error response structure
|
||||||
|
- Pagination format
|
||||||
|
|
||||||
|
3. **Headers**
|
||||||
|
- Authentication headers
|
||||||
|
- Content-Type
|
||||||
|
- Custom headers
|
||||||
|
|
||||||
|
**Standard response format:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": { ... },
|
||||||
|
"meta": {
|
||||||
|
"page": 1,
|
||||||
|
"limit": 20,
|
||||||
|
"total": 100
|
||||||
|
},
|
||||||
|
"links": {
|
||||||
|
"self": "/users?page=1",
|
||||||
|
"next": "/users?page=2"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Standard error format:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": {
|
||||||
|
"code": "VALIDATION_ERROR",
|
||||||
|
"message": "Request validation failed",
|
||||||
|
"details": [
|
||||||
|
{ "field": "email", "message": "Invalid email format" }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6: Authentication & Authorization
|
||||||
|
|
||||||
|
**Define security scheme:**
|
||||||
|
```yaml
|
||||||
|
securitySchemes:
|
||||||
|
bearerAuth:
|
||||||
|
type: http
|
||||||
|
scheme: bearer
|
||||||
|
bearerFormat: JWT
|
||||||
|
apiKey:
|
||||||
|
type: apiKey
|
||||||
|
in: header
|
||||||
|
name: X-API-Key
|
||||||
|
oauth2:
|
||||||
|
type: oauth2
|
||||||
|
flows:
|
||||||
|
authorizationCode:
|
||||||
|
authorizationUrl: /oauth/authorize
|
||||||
|
tokenUrl: /oauth/token
|
||||||
|
scopes:
|
||||||
|
read: Read access
|
||||||
|
write: Write access
|
||||||
|
```
|
||||||
|
|
||||||
|
**Apply security to endpoints:**
|
||||||
|
- Public endpoints (no auth)
|
||||||
|
- Authenticated endpoints (user token)
|
||||||
|
- Admin-only endpoints (role-based)
|
||||||
|
|
||||||
|
### Step 7: Generate OpenAPI Specification
|
||||||
|
|
||||||
|
**Create OpenAPI 3.0+ document:**
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: {project_name} API
|
||||||
|
version: 1.0.0
|
||||||
|
description: |
|
||||||
|
{api_description}
|
||||||
|
|
||||||
|
servers:
|
||||||
|
- url: https://api.example.com/v1
|
||||||
|
description: Production
|
||||||
|
- url: https://staging-api.example.com/v1
|
||||||
|
description: Staging
|
||||||
|
- url: http://localhost:3000/v1
|
||||||
|
description: Development
|
||||||
|
|
||||||
|
paths:
|
||||||
|
/resources:
|
||||||
|
get:
|
||||||
|
summary: List resources
|
||||||
|
operationId: listResources
|
||||||
|
tags:
|
||||||
|
- Resources
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/page'
|
||||||
|
- $ref: '#/components/parameters/limit'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Successful response
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ResourceList'
|
||||||
|
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
Resource:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
required:
|
||||||
|
- id
|
||||||
|
- name
|
||||||
|
|
||||||
|
parameters:
|
||||||
|
page:
|
||||||
|
name: page
|
||||||
|
in: query
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
default: 1
|
||||||
|
limit:
|
||||||
|
name: limit
|
||||||
|
in: query
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
default: 20
|
||||||
|
maximum: 100
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 8: API Documentation
|
||||||
|
|
||||||
|
**Generate API design document with:**
|
||||||
|
|
||||||
|
1. **Overview**
|
||||||
|
- API purpose and scope
|
||||||
|
- Base URL and versioning strategy
|
||||||
|
- Authentication methods
|
||||||
|
|
||||||
|
2. **Quick Start**
|
||||||
|
- Getting API credentials
|
||||||
|
- Making first request
|
||||||
|
- Common patterns
|
||||||
|
|
||||||
|
3. **Resource Reference**
|
||||||
|
- Detailed endpoint documentation
|
||||||
|
- Request/response examples
|
||||||
|
- Error codes
|
||||||
|
|
||||||
|
4. **Best Practices**
|
||||||
|
- Rate limiting guidance
|
||||||
|
- Pagination recommendations
|
||||||
|
- Error handling
|
||||||
|
|
||||||
|
### Step 9: Mock Server Guidance
|
||||||
|
|
||||||
|
**Provide mock server setup:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Using Prism (OpenAPI)
|
||||||
|
npm install -g @stoplight/prism-cli
|
||||||
|
prism mock api-spec.yaml
|
||||||
|
|
||||||
|
# Using json-server (simple)
|
||||||
|
npm install -g json-server
|
||||||
|
json-server --watch db.json
|
||||||
|
|
||||||
|
# Using MSW (frontend mocking)
|
||||||
|
npm install msw --save-dev
|
||||||
|
```
|
||||||
|
|
||||||
|
**Include sample mock data:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"users": [
|
||||||
|
{ "id": "1", "name": "Alice", "email": "alice@example.com" },
|
||||||
|
{ "id": "2", "name": "Bob", "email": "bob@example.com" }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 10: SDK Generation Guidance
|
||||||
|
|
||||||
|
**Client SDK generation options:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# OpenAPI Generator
|
||||||
|
npx @openapitools/openapi-generator-cli generate \
|
||||||
|
-i api-spec.yaml \
|
||||||
|
-g typescript-axios \
|
||||||
|
-o ./sdk
|
||||||
|
|
||||||
|
# Available generators:
|
||||||
|
# - typescript-axios
|
||||||
|
# - typescript-fetch
|
||||||
|
# - python
|
||||||
|
# - go
|
||||||
|
# - java
|
||||||
|
# - csharp
|
||||||
|
```
|
||||||
|
|
||||||
|
**Type generation (TypeScript):**
|
||||||
|
```bash
|
||||||
|
# Using openapi-typescript
|
||||||
|
npx openapi-typescript api-spec.yaml -o types.d.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 11: Validation Checklist
|
||||||
|
|
||||||
|
Before completing:
|
||||||
|
- [ ] All PRD features have corresponding endpoints
|
||||||
|
- [ ] Resource naming follows conventions
|
||||||
|
- [ ] Request/response schemas complete
|
||||||
|
- [ ] Authentication defined for protected endpoints
|
||||||
|
- [ ] Error responses documented
|
||||||
|
- [ ] Pagination implemented for list endpoints
|
||||||
|
- [ ] OpenAPI spec validates (use swagger-cli validate)
|
||||||
|
- [ ] Examples provided for complex endpoints
|
||||||
|
|
||||||
|
### Step 12: Output Files
|
||||||
|
|
||||||
|
**Save to:**
|
||||||
|
- OpenAPI spec: `{output_file}` (api-spec.yaml)
|
||||||
|
- API design doc: `{output_doc}` (api-design.md)
|
||||||
|
|
||||||
|
**Notify user with:**
|
||||||
|
- Summary of endpoints created
|
||||||
|
- Link to specification file
|
||||||
|
- Mock server quick start
|
||||||
|
- Next steps (implementation, SDK generation)
|
||||||
|
|
@ -0,0 +1,467 @@
|
||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: "{{project_name}} API"
|
||||||
|
version: "{{api_version}}"
|
||||||
|
description: |
|
||||||
|
{{api_description}}
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
{{auth_description}}
|
||||||
|
|
||||||
|
## Rate Limiting
|
||||||
|
{{rate_limit_description}}
|
||||||
|
|
||||||
|
contact:
|
||||||
|
name: API Support
|
||||||
|
email: api@example.com
|
||||||
|
license:
|
||||||
|
name: MIT
|
||||||
|
url: https://opensource.org/licenses/MIT
|
||||||
|
|
||||||
|
servers:
|
||||||
|
- url: https://api.{{domain}}/v{{major_version}}
|
||||||
|
description: Production
|
||||||
|
- url: https://staging-api.{{domain}}/v{{major_version}}
|
||||||
|
description: Staging
|
||||||
|
- url: http://localhost:{{port}}/v{{major_version}}
|
||||||
|
description: Development
|
||||||
|
|
||||||
|
tags:
|
||||||
|
# Define tags for each resource group
|
||||||
|
- name: Authentication
|
||||||
|
description: Authentication and authorization endpoints
|
||||||
|
- name: Users
|
||||||
|
description: User management operations
|
||||||
|
# Add more tags as needed
|
||||||
|
|
||||||
|
paths:
|
||||||
|
# Authentication endpoints
|
||||||
|
/auth/login:
|
||||||
|
post:
|
||||||
|
summary: Authenticate user
|
||||||
|
operationId: login
|
||||||
|
tags:
|
||||||
|
- Authentication
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/LoginRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Authentication successful
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/AuthResponse'
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
'422':
|
||||||
|
$ref: '#/components/responses/ValidationError'
|
||||||
|
|
||||||
|
/auth/logout:
|
||||||
|
post:
|
||||||
|
summary: Logout user
|
||||||
|
operationId: logout
|
||||||
|
tags:
|
||||||
|
- Authentication
|
||||||
|
security:
|
||||||
|
- bearerAuth: []
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Logout successful
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
|
||||||
|
# Resource template - copy and customize
|
||||||
|
/resources:
|
||||||
|
get:
|
||||||
|
summary: List resources
|
||||||
|
operationId: listResources
|
||||||
|
tags:
|
||||||
|
- Resources
|
||||||
|
security:
|
||||||
|
- bearerAuth: []
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/page'
|
||||||
|
- $ref: '#/components/parameters/limit'
|
||||||
|
- $ref: '#/components/parameters/sort'
|
||||||
|
- $ref: '#/components/parameters/filter'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Successful response
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ResourceListResponse'
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
|
||||||
|
post:
|
||||||
|
summary: Create resource
|
||||||
|
operationId: createResource
|
||||||
|
tags:
|
||||||
|
- Resources
|
||||||
|
security:
|
||||||
|
- bearerAuth: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/CreateResourceRequest'
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: Resource created
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ResourceResponse'
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
'422':
|
||||||
|
$ref: '#/components/responses/ValidationError'
|
||||||
|
|
||||||
|
/resources/{id}:
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/resourceId'
|
||||||
|
|
||||||
|
get:
|
||||||
|
summary: Get resource by ID
|
||||||
|
operationId: getResource
|
||||||
|
tags:
|
||||||
|
- Resources
|
||||||
|
security:
|
||||||
|
- bearerAuth: []
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Successful response
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ResourceResponse'
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
'404':
|
||||||
|
$ref: '#/components/responses/NotFound'
|
||||||
|
|
||||||
|
patch:
|
||||||
|
summary: Update resource
|
||||||
|
operationId: updateResource
|
||||||
|
tags:
|
||||||
|
- Resources
|
||||||
|
security:
|
||||||
|
- bearerAuth: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/UpdateResourceRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Resource updated
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ResourceResponse'
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
'404':
|
||||||
|
$ref: '#/components/responses/NotFound'
|
||||||
|
'422':
|
||||||
|
$ref: '#/components/responses/ValidationError'
|
||||||
|
|
||||||
|
delete:
|
||||||
|
summary: Delete resource
|
||||||
|
operationId: deleteResource
|
||||||
|
tags:
|
||||||
|
- Resources
|
||||||
|
security:
|
||||||
|
- bearerAuth: []
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Resource deleted
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
'404':
|
||||||
|
$ref: '#/components/responses/NotFound'
|
||||||
|
|
||||||
|
components:
|
||||||
|
securitySchemes:
|
||||||
|
bearerAuth:
|
||||||
|
type: http
|
||||||
|
scheme: bearer
|
||||||
|
bearerFormat: JWT
|
||||||
|
description: JWT authentication token
|
||||||
|
|
||||||
|
apiKey:
|
||||||
|
type: apiKey
|
||||||
|
in: header
|
||||||
|
name: X-API-Key
|
||||||
|
description: API key for service-to-service calls
|
||||||
|
|
||||||
|
parameters:
|
||||||
|
page:
|
||||||
|
name: page
|
||||||
|
in: query
|
||||||
|
description: Page number for pagination
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
minimum: 1
|
||||||
|
default: 1
|
||||||
|
|
||||||
|
limit:
|
||||||
|
name: limit
|
||||||
|
in: query
|
||||||
|
description: Number of items per page
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
minimum: 1
|
||||||
|
maximum: 100
|
||||||
|
default: 20
|
||||||
|
|
||||||
|
sort:
|
||||||
|
name: sort
|
||||||
|
in: query
|
||||||
|
description: Sort field and direction (e.g., -createdAt for descending)
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
example: "-createdAt"
|
||||||
|
|
||||||
|
filter:
|
||||||
|
name: filter
|
||||||
|
in: query
|
||||||
|
description: Filter expression
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
example: "status:active"
|
||||||
|
|
||||||
|
resourceId:
|
||||||
|
name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
description: Resource identifier
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
|
||||||
|
schemas:
|
||||||
|
# Authentication schemas
|
||||||
|
LoginRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- email
|
||||||
|
- password
|
||||||
|
properties:
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
format: password
|
||||||
|
minLength: 8
|
||||||
|
|
||||||
|
AuthResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
accessToken:
|
||||||
|
type: string
|
||||||
|
refreshToken:
|
||||||
|
type: string
|
||||||
|
expiresIn:
|
||||||
|
type: integer
|
||||||
|
description: Token expiry in seconds
|
||||||
|
tokenType:
|
||||||
|
type: string
|
||||||
|
default: Bearer
|
||||||
|
|
||||||
|
# Resource schemas (template)
|
||||||
|
Resource:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
readOnly: true
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 255
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
status:
|
||||||
|
type: string
|
||||||
|
enum: [active, inactive, archived]
|
||||||
|
default: active
|
||||||
|
createdAt:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
readOnly: true
|
||||||
|
updatedAt:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
readOnly: true
|
||||||
|
required:
|
||||||
|
- name
|
||||||
|
|
||||||
|
CreateResourceRequest:
|
||||||
|
allOf:
|
||||||
|
- $ref: '#/components/schemas/Resource'
|
||||||
|
- type: object
|
||||||
|
required:
|
||||||
|
- name
|
||||||
|
|
||||||
|
UpdateResourceRequest:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
status:
|
||||||
|
type: string
|
||||||
|
enum: [active, inactive, archived]
|
||||||
|
|
||||||
|
ResourceResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
data:
|
||||||
|
$ref: '#/components/schemas/Resource'
|
||||||
|
|
||||||
|
ResourceListResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
data:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/Resource'
|
||||||
|
meta:
|
||||||
|
$ref: '#/components/schemas/PaginationMeta'
|
||||||
|
links:
|
||||||
|
$ref: '#/components/schemas/PaginationLinks'
|
||||||
|
|
||||||
|
# Pagination
|
||||||
|
PaginationMeta:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
page:
|
||||||
|
type: integer
|
||||||
|
limit:
|
||||||
|
type: integer
|
||||||
|
total:
|
||||||
|
type: integer
|
||||||
|
totalPages:
|
||||||
|
type: integer
|
||||||
|
|
||||||
|
PaginationLinks:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
self:
|
||||||
|
type: string
|
||||||
|
format: uri
|
||||||
|
first:
|
||||||
|
type: string
|
||||||
|
format: uri
|
||||||
|
prev:
|
||||||
|
type: string
|
||||||
|
format: uri
|
||||||
|
nullable: true
|
||||||
|
next:
|
||||||
|
type: string
|
||||||
|
format: uri
|
||||||
|
nullable: true
|
||||||
|
last:
|
||||||
|
type: string
|
||||||
|
format: uri
|
||||||
|
|
||||||
|
# Error schemas
|
||||||
|
Error:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
error:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
code:
|
||||||
|
type: string
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
details:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
field:
|
||||||
|
type: string
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
responses:
|
||||||
|
Unauthorized:
|
||||||
|
description: Authentication required
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
example:
|
||||||
|
error:
|
||||||
|
code: UNAUTHORIZED
|
||||||
|
message: Authentication required
|
||||||
|
|
||||||
|
Forbidden:
|
||||||
|
description: Permission denied
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
example:
|
||||||
|
error:
|
||||||
|
code: FORBIDDEN
|
||||||
|
message: Permission denied
|
||||||
|
|
||||||
|
NotFound:
|
||||||
|
description: Resource not found
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
example:
|
||||||
|
error:
|
||||||
|
code: NOT_FOUND
|
||||||
|
message: Resource not found
|
||||||
|
|
||||||
|
ValidationError:
|
||||||
|
description: Validation error
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
example:
|
||||||
|
error:
|
||||||
|
code: VALIDATION_ERROR
|
||||||
|
message: Request validation failed
|
||||||
|
details:
|
||||||
|
- field: email
|
||||||
|
message: Invalid email format
|
||||||
|
|
||||||
|
RateLimitExceeded:
|
||||||
|
description: Rate limit exceeded
|
||||||
|
headers:
|
||||||
|
X-RateLimit-Limit:
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
X-RateLimit-Remaining:
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
X-RateLimit-Reset:
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
example:
|
||||||
|
error:
|
||||||
|
code: RATE_LIMIT_EXCEEDED
|
||||||
|
message: Too many requests
|
||||||
|
|
@ -0,0 +1,39 @@
|
||||||
|
# API Design Workflow
|
||||||
|
name: create-api-spec
|
||||||
|
description: "Contract-first API design workflow producing OpenAPI 3.0+ specifications with mock server guidance and client SDK generation recommendations"
|
||||||
|
author: "BMAD"
|
||||||
|
version: "1.0.0"
|
||||||
|
|
||||||
|
# Configuration sources
|
||||||
|
config_source: "{project-root}/_bmad/bmm/config.yaml"
|
||||||
|
user_name: "{config_source}:user_name"
|
||||||
|
communication_language: "{config_source}:communication_language"
|
||||||
|
user_skill_level: "{config_source}:user_skill_level"
|
||||||
|
document_output_language: "{config_source}:document_output_language"
|
||||||
|
planning_artifacts: "{config_source}:planning_artifacts"
|
||||||
|
output_folder: "{planning_artifacts}"
|
||||||
|
date: system-generated
|
||||||
|
|
||||||
|
# Workflow components
|
||||||
|
installed_path: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-api-spec"
|
||||||
|
instructions: "{installed_path}/instructions.md"
|
||||||
|
template: "{installed_path}/openapi.template.yaml"
|
||||||
|
checklist: "{installed_path}/api-checklist.md"
|
||||||
|
|
||||||
|
# Input references
|
||||||
|
prd_doc: "{planning_artifacts}/*prd*.md"
|
||||||
|
architecture_doc: "{planning_artifacts}/*architecture*.md"
|
||||||
|
project_context: "**/project-context.md"
|
||||||
|
|
||||||
|
# Output
|
||||||
|
output_file: "{output_folder}/api-spec.yaml"
|
||||||
|
output_doc: "{output_folder}/api-design.md"
|
||||||
|
|
||||||
|
# API styles supported
|
||||||
|
api_styles:
|
||||||
|
- rest # RESTful API
|
||||||
|
- graphql # GraphQL schema
|
||||||
|
- grpc # Protocol Buffers
|
||||||
|
- websocket # WebSocket events
|
||||||
|
|
||||||
|
standalone: true
|
||||||
Loading…
Reference in New Issue