470 lines
11 KiB
YAML
470 lines
11 KiB
YAML
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
|
|
- name: Resources
|
|
description: Resource 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
|