API Documentation Skill

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

{
  "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

- Secure Development SKILL

- Documentation Portfolio SKILL

Related Documentation

- simon-moon Agent

Tools

- Swagger UI

- ReDoc

- Postman

- Insomnia