OpenAPI и Swagger: что это и в чём разница

Когда в задаче просят «дать Swagger», обычно нужен один из двух результатов: файл с описанием API или страница, на которой удобно смотреть его операции. Оба варианта связаны с OpenAPI, но работать с ними предстоит по-разному. Если вам дали ссылку на интерактивную документацию, из неё ещё не ясно, где хранится исходное описание интерфейса и можно ли использовать его в других инструментах.

OpenAPI задаёт формат описания HTTP API. Swagger сегодня называют набор инструментов, которые помогают создавать, читать и использовать такие описания. Путаница возникла не случайно: когда-то Swagger называлась и сама спецификация.

Разберём историю и разницу терминов, затем посмотрим на небольшой контракт получения заказа. На нём видно, что именно может сообщить YAML-файл, что показывает Swagger UI и какие проверки нужны, прежде чем полагаться на описание работающего API.

Что такое OpenAPI

OpenAPI — открытая спецификация для описания HTTP API независимо от языка реализации. Она задаёт единый способ записывать пути, HTTP-методы, параметры, тела запросов, ответы и требования к безопасности. Например, из описания можно узнать, какой параметр нужен для получения заказа и какое тело предполагается у ответа 200, не читая реализацию сервера. Такое назначение закреплено в спецификации OpenAPI.

Описание OpenAPI можно записать в YAML или JSON. Это два представления одного формата данных. Важна структура полей, а не расширение файла: инструменты читают документ и строят по нему представление для человека, заготовку клиента или другие производные результаты.

Сам файл часто называется openapi.yaml. Он может храниться рядом с кодом сервиса и изменяться вместе с интерфейсом. Например, при появлении нового поля ответа изменение следует отразить и в описании. Насколько описание действительно соответствует реализации, проверяют отдельно.

Какая версия OpenAPI актуальна

На 3 ноября 2026 года актуальная опубликованная версия спецификации — 3.2.1. Она выпущена 10 сентября 2026 года; сведения есть в официальном каталоге и истории редакций OAS 3.2.1. При этом в проектах продолжают встречаться документы веток 3.0 и 3.1.

Не путайте номер опубликованной спецификации с поддержкой конкретной версии в вашем редакторе или генераторе. Если описание использует возможности OAS 3.2, инструмент, понимающий только 3.0, может его разобрать не полностью.

Что такое Swagger и откуда взялось название

Сначала Swagger была названием самой спецификации описания API. Затем стандарт передали OpenAPI Initiative и переименовали в OpenAPI Specification.

Спецификация Swagger 2.0 стала основой OpenAPI после передачи в OpenAPI Initiative в 2015 году. В истории стандарта указаны две отдельные даты: выпуск Swagger 2.0 в 2014 году и передача спецификации 31 декабря 2015 года. Поэтому в старых проектах можно увидеть swagger: "2.0", а в современных документах — поле openapi с версией 3.x.

Сегодня Swagger — это семейство инструментов, работающих с описаниями OpenAPI. Самые известные — Swagger UI, Swagger Editor и Swagger Codegen. На сайте Swagger они представлены как инструменты просмотра, редактирования и генерации кода.

В разговоре выражение «открыть Swagger» обычно означает открыть Swagger UI с документацией сервиса. А фраза «у нас Swagger 2.0» может описывать формат старого файла. Если нужно уточнить задачу, достаточно спросить, требуется ли само описание API или интерфейс для работы с ним.

В чём разница между OpenAPI и Swagger

OpenAPI задаёт общие правила, по которым оформляют описание API. Инструменты Swagger используют такие описания для разных задач. Это видно по тому, какой артефакт нужен на входе и что получается на выходе.

Название	Что это	Для чего применяется
OpenAPI Specification	Стандарт описания HTTP API	Согласовать структуру операций, параметров и ответов
OpenAPI-документ	Конкретный YAML- или JSON-файл, составленный по стандарту	Передать описание другим командам и инструментам
Swagger UI	Интерфейс для просмотра документа	Прочитать список операций, параметры и схемы ответов
Swagger Editor	Редактор описаний	Подготовить и исправить OpenAPI-документ
Swagger Codegen	Генератор кода	Получить заготовки клиентов или серверной части по описанию

В примере ниже файл openapi.yaml описывает GET /orders/{orderId}, а Swagger UI показывает эту операцию на отдельной странице документации. Другой просмотрщик может оформить те же сведения иначе, но исходное описание останется тем же.

Поэтому для работы с контрактом полезно хранить исходный YAML или JSON вместе с кодом API и обновлять его при изменении интерфейса. Страница Swagger UI помогает читать описание, но не заменяет доступ к самому файлу.

Пример OpenAPI на YAML: описание получения заказа

Возьмём маленький интерфейс интернет-магазина. По запросу GET /orders/{orderId} он должен возвращать заказ в JSON либо сообщать, что запись не найдена. В примере используется OpenAPI 3.1.0: это выбранная версия синтаксиса файла, а не утверждение, что она последняя.

Сохраните описание как examples/openapi.yaml:

openapi: 3.1.0
info:
  title: Orders API
  version: "1.0"
paths:
  /orders/{orderId}:
    get:
      summary: Получить заказ
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Заказ найден
          content:
            application/json:
              schema:
                type: object
                required: [id, status]
                properties:
                  id:
                    type: integer
                  status:
                    type: string
        "404":
          description: Заказ не найден

Поле openapi обозначает версию спецификации, а info.version — версию самого описания. В этом случае 3.1.0 определяет, как трактовать поля документа, а "1.0" относится к версии API-описания. Это различие закреплено в нормативном тексте OAS 3.1.

В paths указан шаблон адреса, а внутри него — операция get. Параметр orderId передаётся в пути, обязателен и имеет целочисленный тип. У ответа 200 задан тип содержимого application/json; схема требует два поля: целочисленный id и строковый status. Для 404 здесь указано лишь описание: тело ответа не задано.

Проверяем учебный файл

Сначала проверим весь документ специализированным валидатором OpenAPI 3.1. Затем отдельно зафиксируем ожидаемые поля и проверим схему JSON-ответа на положительном и отрицательных примерах. Это разделяет общие правила OAS и свойства конкретного учебного контракта.

Сохраните рядом с YAML файл examples/check_openapi.py:

from copy import deepcopy
from pathlib import Path

from jsonschema import Draft202012Validator
from openapi_spec_validator import OpenAPIV31SpecValidator, validate
from yaml import safe_load


def main() -> None:
    path = Path(__file__).with_name("openapi.yaml")
    document = safe_load(path.read_text(encoding="utf-8"))
    assert isinstance(document, dict)
    assert document["openapi"] == "3.1.0"
    assert document["info"]["title"] == "Orders API"
    assert document["info"]["version"] == "1.0"
    validate(document, cls=OpenAPIV31SpecValidator)

    invalid_document = deepcopy(document)
    del invalid_document["info"]
    assert list(OpenAPIV31SpecValidator(invalid_document).iter_errors())

    operation = document["paths"]["/orders/{orderId}"]["get"]
    path_parameter = next(
        p for p in operation["parameters"] if p["name"] == "orderId"
    )
    assert path_parameter["in"] == "path"
    assert path_parameter["required"] is True
    assert path_parameter["schema"]["type"] == "integer"

    responses = operation["responses"]
    assert "200" in responses and "404" in responses
    response_schema = responses["200"]["content"]["application/json"]["schema"]
    Draft202012Validator.check_schema(response_schema)
    validator = Draft202012Validator(response_schema)
    assert validator.is_valid({"id": 42, "status": "paid"})
    assert not validator.is_valid({"id": "42", "status": "paid"})
    assert not validator.is_valid({"id": 42})

    print("openapi: 3.1.0")
    print("oas_document: valid")
    print("oas_negative_control: missing info rejected")
    print("operation: GET /orders/{orderId}")
    print("path_parameter: orderId required")
    print("response_schema: valid example accepted")
    print("negative_controls: 2 rejected")


if __name__ == "__main__":
    main()

Потребуются Python и пакеты PyYAML==6.0.3, jsonschema==4.26.0 и openapi-spec-validator==0.9.0. Последний проверяет весь документ по правилам OpenAPI 3.1; официальный Python API показан в документации валидатора. Из каталога, где находится папка examples, запустите:

python -m pip install "PyYAML==6.0.3" "jsonschema==4.26.0" "openapi-spec-validator==0.9.0"
python -I examples/check_openapi.py

Для этого документа команда выводит:

openapi: 3.1.0
oas_document: valid
oas_negative_control: missing info rejected
operation: GET /orders/{orderId}
path_parameter: orderId required
response_schema: valid example accepted
negative_controls: 2 rejected

Валидатор принял полный учебный документ как OpenAPI 3.1 и отклонил вариант без обязательного блока info. Строка negative_controls относится уже к схеме ответа: она отклонила объект со строковым id и объект без обязательного поля status. Скрипт не обращался к HTTP-серверу. Далее тот же файл показан в Swagger UI; ни проверка документа, ни его отображение не подтверждают поведение настоящего API.

Как инструменты Swagger используют описание

Swagger UI отображает описание OpenAPI как интерактивную документацию. Он читает документ и показывает операции, параметры, типы запросов и ответов. Если для API настроен доступный сервер, в интерфейсе можно отправлять запросы.

На снимке Swagger UI прочитал тот же examples/openapi.yaml, который разобран выше. Интерфейс показывает описание операции, но HTTP-сервер для этого кадра не запускался: видимая документация подтверждает чтение файла, а не работу API.

Swagger Editor нужен, когда описание создают или редактируют. Он позволяет работать с YAML/JSON и видеть замечания к документу. Редактор полезен на этапе согласования API: можно обсуждать пути и поля ещё до появления рабочей реализации.

Swagger Codegen использует документ как вход для генерации клиентских библиотек и серверных заготовок. Например, по GET /orders/{orderId} можно подготовить программный метод для вызова операции. Полученная заготовка не реализует сама по себе поиск заказа в базе и не подтверждает правильность бизнес-логики. Назначение трёх инструментов описано в официальном обзоре Swagger.

При выборе инструментов проверяйте поддержку версии OpenAPI, указанной в документе. На снимке учебный файл отображается в Swagger UI 5.34.1; поддержку того же формата другими инструментами следует уточнять отдельно.

Почему правильное описание не гарантирует правильный API

Файл OpenAPI описывает ожидаемый интерфейс, но сам по себе не проверяет ответы работающего сервера. Допустим, в документе для GET /orders/{orderId} указан статус 200 и тело {"id": 42, "status": "paid"}. Сервер может вернуть {"id": "42"}: форма ответа уже расходится с описанием, хотя YAML остаётся корректным.

Поэтому при работе с контрактом различайте три проверки:

1. Структура документа. Можно ли разобрать файл и соответствует ли его содержимое правилам нужной версии OpenAPI? В примере полный документ проверяет openapi-spec-validator, а отдельные утверждения дополнительно фиксируют ожидаемые поля. Даже успешный валидатор не проверяет работу сервера и поддержку документа конкретной версией UI или генератора.
2. Работа средства просмотра. Может ли выбранная версия Swagger UI или Editor обработать документ и правильно показать операции? Это проверяется отдельно на целевом инструменте.
3. Поведение сервера. Совпадают ли реальные статусы, заголовки и JSON-ответы с описанием? Для этого нужны HTTP-запросы к работающему API и сопоставление наблюдений с контрактом.

Даже совпадение статусов и схем ответов не доказывает правильность предметных правил. Например, доступность заказа только его владельцу проверяется отдельно от формата JSON.

Выбирая версию OpenAPI для проекта, учитывайте не только опубликованные редакции стандарта, но и поддержку выбранного формата в инструментах команды.

Когда использовать OpenAPI, а когда Swagger

Если вы хотите согласовать и хранить описание HTTP API, начните с OpenAPI-документа. Он содержит операции, параметры и ожидаемые ответы в формате, который могут читать разные инструменты. Для просмотра описания в браузере подойдёт Swagger UI, для редактирования — Swagger Editor, для генерации заготовок кода — Swagger Codegen.

Один небольшой пример уже показывает границу: YAML сообщает, что GET /orders/{orderId} должен принимать orderId и возвращать поля id и status. В проверенном окружении валидатор принял учебный OpenAPI-документ, а отдельные проверки подтвердили выбранные свойства схемы ответа. Выполнение контракта сервером устанавливается по реальным HTTP-ответам.

Для работы команды важны обе части: поддерживать описание в актуальном состоянии и отдельно проверять реализацию. Тогда документация помогает использовать API, а не создаёт ложную уверенность в его поведении.

Источники

• Официальный каталог опубликованных версий OpenAPI
• Нормативный текст OAS 3.2.1, поля, версии и история спецификации
• Нормативный текст ветки OAS 3.1, используемой в учебном примере
• Официальный обзор Swagger UI, Swagger Editor и Swagger Codegen
• Объяснение различий между Swagger и OpenAPI от разработчиков инструментов
• История названия Swagger и передачи спецификации OpenAPI Initiative
• Официальный Python API полного валидатора OpenAPI и пример отрицательной проверки