Swagger / OpenAPI

Что такое Swagger и OpenAPI

OpenAPI — формат описания HTTP-API: один файл в YAML или JSON, где перечислены все эндпоинты, методы, параметры, схемы запросов и ответов, коды ошибок и способ авторизации. Файл машиночитаемый, поэтому по нему генерируют документацию, клиентов и тесты.

Swagger — набор инструментов, работающих с этим файлом: Swagger UI (интерактивная документация в браузере), Swagger Editor (редактор с валидацией), Swagger Codegen (генератор кода).

Путаница в названиях историческая: формат родился как Swagger Specification, затем был передан в OpenAPI Initiative и переименован в OpenAPI — версия Swagger 2.0 стала предшественницей OpenAPI 3.x. Сегодня строго: OpenAPI — это спецификация, Swagger — инструменты. В разговоре «сваггер» обычно означает ту самую страницу с документацией, где можно нажать Try it out.

Как выглядит спецификация

openapi: 3.0.3
info:
  title: Weather API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /cities/{city}/weather:
    get:
      summary: Погода в городе
      parameters:
        - name: city
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Weather'
        '404':
          description: Город не найден
components:
  schemas:
    Weather:
      type: object
      required: [city, temperature_c]
      properties:
        city: { type: string }
        temperature_c: { type: number }

Из этих 30 строк получается и страница документации, и клиентская библиотека, и проверка ответов в тестах.

Зачем это нужно на практике

• Документация не врёт. Спецификация лежит рядом с кодом и правится в том же коммите — в отличие от вики, которая устаревает за месяц.
• Кодогенерация. openapi-generator собирает клиента для нужного языка и мок-сервер с примерами ответов.
• Contract-first. Фронтенд и бэкенд договариваются о схеме заранее и работают параллельно, а не ждут друг друга.
• Валидация в CI. Тест проверяет, что реальные ответы сервиса соответствуют схеме.

Два подхода к спецификации

Многие фреймворки отдают спецификацию сами: FastAPI на Python публикует Swagger UI по /docs и сам файл по /openapi.json без единой строчки настройки.

Поднять Swagger UI

docker run -p 8080:8080 \
  -e SWAGGER_JSON=/spec/openapi.yaml \
  -v $(pwd):/spec \
  swaggerapi/swagger-ui

Открывается http://localhost:8080 с интерактивной документацией. В Docker Compose такой контейнер часто ставят рядом с сервисом на dev-окружении.

Отдавать Swagger UI наружу вместе с production-API стоит осознанно: страница показывает все эндпоинты и структуру данных. Если API внутренний, документацию закрывают авторизацией или оставляют только в закрытом контуре — сама спецификация при этом остаётся в репозитории.

Связанные термины

• API — то, что описывает спецификация
• REST API — стиль API, под который заточен OpenAPI
• API endpoint — единица описания в разделе paths
• HTTP-ошибки — коды ответов, перечисляемые в responses
• CI/CD — где проверяют соответствие API спецификации