Где велась документация по REST API?

Где хранится документация REST API

Это практический вопрос о organization и tools для документирования API, с которыми работают frontend-разработчики. Расскажу о лучших практиках и инструментах.

Основные места хранения документации

1. Swagger/OpenAPI

Мост популярный инструмент для документирования REST API:

// Пример использования в проекте
// docs/openapi.yaml
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        200:
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string

Средство Swagger UI генерирует интерактивный интерфейс для тестирования:

# Запуск Swagger UI
npm install swagger-ui-express

// Express пример
const express = require("express");
const swaggerUi = require("swagger-ui-express");
const swaggerDocument = require("./swagger.json");

const app = express();

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocument));
app.listen(3000);

2. Postman Collections

Популярный инструмент для тестирования и документирования:

{
  "info": {
    "name": "My API Collection",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Get Users",
      "request": {
        "method": "GET",
        "url": "{{base_url}}/api/v1/users"
      },
      "response": []
    }
  ]
}

Основные преимущества:

• Интерактивное тестирование
• Автоматическое создание документации
• Экспорт в другие форматы
• Командная работа

3. Markdown документация в репозитории

Простой и эффективный подход:

# API Documentation

## GET /api/v1/users

Получить список всех пользователей.

### Query Parameters

- `page` (optional): number - Номер страницы
- `limit` (optional): number - Количество на странице

### Response 200

```json
{
  "data": [

{
  "id": "123",
  "name": "John",
  "email": "john@example.com"
}

  ],
  "pagination": {

"page": 1,
"total": 100

  }

}

Example Request

curl -X GET "http://localhost:3000/api/v1/users?page=1&limit=10"

### Frontend интеграция

Когда документация доступна, frontend использует ее для:**

```javascript
// api.ts или service файл
import axios from "axios";

interface User {
  id: string;
  name: string;
  email: string;
}

interface UsersResponse {
  data: User[];
  pagination: {
    page: number;
    total: number;
  };
}

// Запрос соответствует документации
class UserService {
  private baseUrl = process.env.REACT_APP_API_URL;
  
  async getUsers(page: number = 1, limit: number = 10): Promise<UsersResponse> {
    const response = await axios.get<UsersResponse>(
      `${this.baseUrl}/api/v1/users`,
      {
        params: { page, limit }
      }
    );
    return response.data;
  }
}

4. Wiki (GitHub Wiki, Notion, Confluence)

Для крупных проектов:

# API Guidelines

## Base URL

- Production: https://api.example.com/api/v1
- Development: http://localhost:3000/api/v1

## Authentication

Все запросы требуют Bearer токен:

Authorization: Bearer <token>

## Error Handling

### Error Response Format

```json
{
  "error": {

"code": "VALIDATION_ERROR",
"message": "Invalid input",
"details": {
  "field": "email",
  "reason": "Invalid email format"
}

  }

}

**5. IntelliJ/VS Code с плагинами**

```json
// .vscode/settings.json
{
  "[json]": {
    "editor.formatOnSave": true
  },
  "extensions": [
    "humao.rest-client",
    "postman.postman-for-vscode"
  ]
}

REST Client пример (VS Code)

### Get all users
GET http://localhost:3000/api/v1/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer token123

### Create new user
POST http://localhost:3000/api/v1/users HTTP/1.1
Content-Type: application/json

{
  "name": "John",
  "email": "john@example.com"
}

Лучшие практики документирования

1. Keep it Updated

// Версионирование API
export const API_VERSION = "v1";
export const BASE_URL = `${process.env.REACT_APP_API_URL}/api/${API_VERSION}`;

// Проверяйте документацию при обновлении
// docs/API_CHANGELOG.md

2. Include Examples

// Хорошая документация всегда содержит примеры
// Как успешный случай
// Так и ошибки

3. Type Safety

// Генерируйте TypeScript типы из OpenAPI
import type { components } from "./generated/api";

type User = components["schemas"]["User"];

function displayUser(user: User) {
  return user.name;
}

Полный workflow

1. Backend разработчик пишет OpenAPI spec
2. Frontend разработчик смотрит документацию
3. Code generator создает TypeScript типы
4. Frontend код полностью типизирован
5. API клиент имеет intellisense поддержку

Инструменты которые часто встречаются

• Swagger/OpenAPI — индустриальный стандарт
• GraphQL — альтернатива REST (самодокументируемая)
• Postman — интерактивное тестирование
• Dredd — автоматическое тестирование API
• API Blueprint — markdown-based документация

Заключение

Документация REST API обычно хранится в нескольких местах:

• OpenAPI/Swagger для полной спецификации
• README/Wiki для гайдов и examples
• Postman Collection для интерактивного тестирования
• Код с JSDoc/TypeScript комментариями

Хорошая документация ускоряет разработку frontend и снижает количество ошибок при интеграции с API.