API Documentation: как писать документацию, которую читают

# API Documentation

## 1. Getting Started (Начало работы)
- Введение в API
- Быстрый старт (Quick Start)
- Аутентификация
- Базовый пример использования

## 2. Authentication (Аутентификация)
- Типы аутентификации
- Получение токена
- Использование токена
- Refresh token
- Обработка ошибок аутентификации

## 3. Endpoints (Endpoints)
- Обзор всех endpoints
- Группировка по ресурсам
- Детальное описание каждого endpoint

## 4. Request/Response (Запросы и ответы)
- Форматы данных
- Примеры запросов
- Примеры ответов
- Коды состояний

## 5. Errors (Ошибки)
- Список всех ошибок
- Коды ошибок
- Примеры обработки ошибок

## 6. Rate Limiting (Ограничение запросов)
- Лимиты запросов
- Заголовки rate limiting
- Обработка превышения лимитов

## 7. SDKs & Libraries (SDK и библиотеки)
- Доступные SDK
- Примеры использования
- Установка

## 8. Changelog (История изменений)
- История версий API
- Breaking changes
- Deprecated endpoints

## 9. Support (Поддержка)
- FAQ
- Контакты поддержки
- Community

## Примеры запросов

### JavaScript (Fetch)
\`\`\`javascript
const response = await fetch('https://api.example.com/v1/users/123', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  }
});

const user = await response.json();
console.log(user);
\`\`\`

### Python (Requests)
\`\`\`python
import requests

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.example.com/v1/users/123',
    headers=headers
)

user = response.json()
print(user)
\`\`\`

### cURL
\`\`\`bash
curl -X GET https://api.example.com/v1/users/123 \
  -H "Authorization: Bearer {token}"
\`\`\`

### Node.js (Axios)
\`\`\`javascript
const axios = require('axios');

const response = await axios.get(
  'https://api.example.com/v1/users/123',
  {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

console.log(response.data);
\`\`\`

  
Try it out
  

    
    Send Request
  
  
  

    
  

// Пример ошибки валидации (400 Bad Request)
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "fields": {
        "email": ["Email is required", "Invalid email format"],
        "password": ["Password must be at least 8 characters"]
      }
    },
    "request_id": "req_1234567890"
  }
}

// Пример ошибки аутентификации (401 Unauthorized)
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token",
    "details": {
      "reason": "token_expired",
      "expired_at": "2025-11-07T12:00:00Z"
    },
    "request_id": "req_1234567890"
  }
}

// Пример ошибки rate limiting (429 Too Many Requests)
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 100,
      "remaining": 0,
      "reset_at": "2025-11-07T13:00:00Z"
    },
    "request_id": "req_1234567890"
  }
}

// JavaScript пример обработки ошибок
async function getUser(id) {
  try {
    const response = await fetch(`/api/v1/users/${id}`, {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });

    if (!response.ok) {
      const error = await response.json();
      
      switch (error.error.code) {
        case 'UNAUTHORIZED':
          // Токен истек, обновляем его
          await refreshToken();
          return getUser(id); // Повторяем запрос
          
        case 'NOT_FOUND':
          console.error('User not found:', id);
          return null;
          
        case 'RATE_LIMIT_EXCEEDED':
          // Ждем до reset_at
          const resetTime = new Date(error.error.details.reset_at);
          await sleep(resetTime - Date.now());
          return getUser(id); // Повторяем запрос
          
        default:
          throw new Error(error.error.message);
      }
    }

    return await response.json();
  } catch (error) {
    console.error('Failed to get user:', error);
    throw error;
  }
}

# Changelog

## [2.0.0] - 2025-11-07

### Breaking Changes
- Удален endpoint `GET /api/v1/users/{id}/profile` 
  Используйте `GET /api/v1/users/{id}` вместо него
- Изменен формат ответа для `POST /api/v1/users`
  Теперь возвращается объект `user` вместо массива
  
### Added
- Новый endpoint `GET /api/v1/users/{id}/activities` для получения активности пользователя
- Поддержка фильтрации по дате для `GET /api/v1/orders`
- Поля `last_login_at` и `is_active` в модели пользователя

### Changed
- Улучшена производительность `GET /api/v1/users` (время ответа снижено на 40%)
- Обновлена валидация email (теперь поддерживает международные домены)

### Deprecated
- Endpoint `GET /api/v1/products/legacy` помечен как deprecated
  Будет удален в версии 3.0.0. Используйте `GET /api/v1/products`

### Fixed
- Исправлена ошибка при создании пользователя с длинным именем
- Исправлена проблема с кэшированием в `GET /api/v1/products`

### Security
- Улучшена защита от SQL injection
- Добавлена дополнительная валидация токенов

---

## [1.2.0] - 2025-10-15

### Added
- Поддержка pagination для всех списков
- Новые фильтры для поиска пользователей

### Fixed
- Исправлена ошибка rate limiting для новых ключей API

---

## [1.1.0] - 2025-09-20

### Added
- Webhook для событий создания пользователя
- Поддержка bulk operations для заказов

### Changed
- Улучшена документация по аутентификации

# Changelog

All notable changes to this API will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Planned feature 1
- Planned feature 2

### Changed
- Planned change 1

## [2.0.0] - 2025-11-07

### [Added]
- New endpoint for user activities

### [Changed]
- Improved performance for users list

### [Deprecated]
- Old endpoint `/api/v1/users/legacy`

### [Removed]
- Removed deprecated endpoint `/api/v1/users/old`

### [Fixed]
- Fixed validation error for long names

### [Security]
- Enhanced token validation

# openapi.yaml
openapi: 3.0.0
info:
  title: Example API
  description: API для управления пользователями
  version: 2.0.0
  contact:
    name: API Support
    email: support@example.com

servers:
  - url: https://api.example.com/v1
    description: Production server

paths:
  /users/{id}:
    get:
      summary: Получить пользователя
      description: Возвращает информацию о пользователе по его ID
      operationId: getUserById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: ID пользователя
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Пользователь не найден
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: "123"
        email:
          type: string
          format: email
          example: "user@example.com"
        name:
          type: string
          example: "John Doe"
        created_at:
          type: string
          format: date-time
          example: "2025-01-15T10:30:00Z"
    
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

// Express.js с swagger-jsdoc
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Example API',
      version: '2.0.0',
      description: 'API для управления пользователями'
    },
    servers: [
      {
        url: 'https://api.example.com/v1',
        description: 'Production server'
      }
    ]
  },
  apis: ['./routes/*.js'] // Путь к файлам с комментариями
};

const swaggerSpec = swaggerJsdoc(swaggerOptions);

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

/**
 * @swagger
 * /users/{id}:
 *   get:
 *     summary: Получить пользователя
 *     tags: [Users]
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: Успешный ответ
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 */
app.get('/api/v1/users/:id', getUserById);

// Express.js с ReDoc
const express = require('express');
const app = express();
const path = require('path');
const fs = require('fs');

// Загружаем OpenAPI спецификацию
const openApiSpec = JSON.parse(
  fs.readFileSync(path.join(__dirname, 'openapi.json'), 'utf8')
);

// HTML для ReDoc
const redocHtml = `


  
    
    
    
    
    
  
  
    
    
  

`;

app.get('/docs', (req, res) => {
  res.send(redocHtml);
});

app.get('/api-docs/openapi.json', (req, res) => {
  res.json(openApiSpec);
});

app.listen(3000);

// ReadMe API Explorer интеграция
// Установка: npm install readmeio

const readme = require('readmeio');

// Middleware для логирования запросов в ReadMe
app.use((req, res, next) => {
  // Сохраняем оригинальный res.send
  const originalSend = res.send.bind(res);

  res.send = function(data) {
    // Отправляем в ReadMe для анализа
    readme.log({
      apiKey: process.env.README_API_KEY,
      userId: req.user?.id,
      label: req.user?.email,
      email: req.user?.email,
      method: req.method,
      url: req.originalUrl,
      statusCode: res.statusCode,
      request: {
        headers: req.headers,
        body: req.body,
        query: req.query
      },
      response: {
        body: data
      }
    }).catch(console.error);

    return originalSend(data);
  };

  next();
});

☐ Есть раздел Getting Started с быстрым стартом
☐ Все endpoints документированы
☐ Есть примеры запросов для каждого endpoint
☐ Есть примеры ответов (успешных и с ошибками)
☐ Документированы все возможные ошибки
☐ Описаны все параметры запросов
☐ Описаны все поля ответов
☐ Есть примеры для популярных языков (JS, Python, cURL)
☐ Ведется changelog
☐ Документация доступна в разных форматах (HTML, PDF)
☐ Есть поиск по документации
☐ Настроена аналитика использования
☐ Документация регулярно обновляется
☐ Есть контакты поддержки
☐ Добавлены FAQ для частых вопросов