Purpose
Provides comprehensive API documentation that enables developers to quickly understand and integrate with APIs through clear examples, authentication guidance, and error handling.
Rules
OpenAPI/Swagger Specification
MUST USE OpenAPI 3.0+:
openapi: 3.0.0
info:
title: Hack23 API
version: 1.0.0
description: Cybersecurity services API
contact:
email: api@hack23.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.hack23.com/v1
description: Production
- url: https://staging-api.hack23.com/v1
description: Staging
paths:
/users:
get:
summary: List users
operationId: listUsers
tags: [Users]
security:
- bearerAuth: []
parameters:
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
components:
schemas:
User:
type: object
required: [id, email]
properties:
id:
type: string
format: uuid
email:
type: string
format: email
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
API Reference Structure
MUST INCLUDE:
1. Overview & Getting Started
- What the API does
- Base URL
- Authentication
- Rate limits
- Quick start example
2. Authentication
- How to obtain credentials
- How to authenticate requests
- Token refresh process
- Security best practices
3. Endpoints
- HTTP method and path
- Description
- Request parameters
- Request body schema
- Response schema
- Error responses
- Code examples
4. Error Handling
- Error code list
- Error response format
- Common errors
- Troubleshooting
5. SDKs & Libraries
- Official SDK links
- Community libraries
- Code samples
6. Changelog
- Version history
- Breaking changes
- Migration guides
Code Examples
MUST PROVIDE examples in:
- cURL
- JavaScript/Node.js
- Python
- (Other popular languages as needed)
Example:
## Create User
`POST /users`
Creates a new user account.
### Request Body
```json
{
"email": "user@example.com",
"name": "John Doe"
}
Example Request (cURL)
curl -X POST https://api.hack23.com/v1/users \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","name":"John Doe"}'
Example Request (JavaScript)
const response = await fetch('https://api.hack23.com/v1/users', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'user@example.com',
name: 'John Doe'
})
});
const user = await response.json();
Response (201 Created)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "user@example.com",
"name": "John Doe",
"createdAt": "2026-02-06T10:00:00Z"
}
### Error Documentation
**Standard Error Format:**
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email format",
"details": [
{
"field": "email",
"message": "Must be a valid email address"
}
],
"requestId": "req_123456",
"timestamp": "2026-02-06T10:00:00Z"
}
}
Related Policies
Related Documentation
Tools
- Swagger UI
- ReDoc
- Postman
- Insomnia