Документирование API (Swagger/OpenAPI) для веб-приложения

Документирование API (Swagger/OpenAPI) для веб-приложения

OpenAPI (бывший Swagger) — стандарт описания REST API в формате YAML или JSON. Документация в OpenAPI-формате позволяет автоматически генерировать интерактивный UI (Swagger UI, Redoc), клиентские SDK и серверные заглушки.

OpenAPI 3.1 структура

openapi: 3.1.0
info:
  title: Articles API
  version: 1.0.0
  description: |
    REST API для управления статьями.
    ## Аутентификация
    Bearer token в заголовке `Authorization: Bearer <token>`

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

paths:
  /articles:
    get:
      tags: [Articles]
      summary: Список статей
      operationId: listArticles
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1, minimum: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
        - name: status
          in: query
          schema: { type: string, enum: [draft, published, archived] }
      responses:
        '200':
          description: Список статей
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ArticleList' }
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []

components:
  schemas:
    Article:
      type: object
      required: [id, title, status, createdAt]
      properties:
        id: { type: string, format: uuid, example: "550e8400-e29b-41d4-a716-446655440000" }
        title: { type: string, maxLength: 200, example: "Заголовок статьи" }
        status: { type: string, enum: [draft, published, archived] }
        createdAt: { type: string, format: date-time }

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

  responses:
    Unauthorized:
      description: Не авторизован
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

Code-first vs Design-first

Design-first: сначала пишется OpenAPI YAML, затем реализация. Обеспечивает API-first подход, контракт до начала разработки.

Code-first: аннотации/декораторы в коде генерируют OpenAPI. Удобнее для существующих проектов.

Laravel (PHP) — code-first через dedoc/scramble:

// Автоматически генерирует OpenAPI из роутов и PHPDoc
composer require dedoc/scramble

// В AppServiceProvider
Scramble::configure()
    ->withDocumentTransformer(function (OpenApi $openApi) {
        $openApi->secure(SecurityScheme::http('bearer'));
    });

Node.js — через tsoa или Fastify:

// Fastify + @fastify/swagger
fastify.register(fastifySwagger, {
  openapi: { info: { title: 'API', version: '1.0' } }
});
fastify.register(fastifySwaggerUi, { routePrefix: '/docs' });

fastify.get('/articles', {
  schema: {
    querystring: { type: 'object', properties: { page: { type: 'integer' } } },
    response: { 200: { $ref: 'ArticleList#' } }
  }
}, handler);

Swagger UI vs Redoc

Swagger UI: интерактивный, позволяет тестировать API прямо в браузере. Встраивается как статика или через npm.

Redoc: красивее выглядит для публичной документации, три-панельный layout, без интерактивности.

Можно использовать оба: Redoc для публичной документации, Swagger UI для разработчиков.

Валидация по схеме

OpenAPI-схема используется для валидации входящих запросов:

// Express + express-openapi-validator
app.use(OpenApiValidator.middleware({
  apiSpec: './openapi.yaml',
  validateRequests: true,
  validateResponses: true, // полезно в dev для проверки ответов сервера
}));

Сроки

Написание OpenAPI-спецификации для существующего API (20–30 эндпоинтов): 2–4 дня. Настройка Swagger UI + валидации + генерации SDK: 1 день дополнительно.