api-documentation（API 文档）

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:

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