APIСтандартизация
тема 1 Открыть слайдами →

Часть 6 из 15 · слайды 37–53

OpenAPI

Контракт спроектирован. Теперь его нужно записать так, чтобы документ не разошёлся с кодом.

  1. 37README может перестать соответствовать коду
  2. 38Машиночитаемое описание HTTP API
  3. 39OpenAPI 3.2 и OpenAPI 3.1 — не одно и то же
  4. 40Swagger и OpenAPI нельзя считать синонимами
  5. 41Что входит в экосистему Swagger
  6. 42OpenAPI document имеет стандартную структуру
  7. 43API должно представиться
  8. 44Где доступен API
  9. 45Endpoints необходимо группировать
  10. 46paths описывает ресурсы
  11. 47Каждый method внутри path — отдельная operation
  12. 48OpenAPI различает расположение параметров
  13. 49Body тоже имеет формальную схему
  14. 50Документируется не только успешный ответ
  15. 51Повторяющиеся схемы следует переиспользовать
  16. 52Механизм авторизации должен быть описан
  17. 53Схема отвечает «что допустимо», example — «как это выглядит»

37README может перестать соответствовать коду

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

Документация говорит, что POST /tickets принимает:

README.md
{
  "title": "..."
}

Разработчик добавляет обязательное поле description, но README не обновляет. Клиенты отправляют запрос по документации и получают 422.

результат

CODE ≠ DOCUMENTATION

Такое состояние называется API documentation drift — расхождение документации и реализации.

  1. CODEdescription обязателен
  2. mismatch
  3. DOCSтолько title

38Машиночитаемое описание HTTP API

OpenAPI Specification определяет стандартный формат описания HTTP API.

В документе OpenAPI можно описать:

  • endpoints и operations;
  • parameters;
  • request bodies;
  • responses;
  • schemas;
  • authentication;
  • metadata.

OpenAPI предназначен одновременно для людей и программ: по нему строится документация, генерируется клиентский код и проверяются запросы.

spec.openapis.org · OAS 3.2.0СКРИНШОТ · 15.09.2026
OpenAPI Specification v3.2.0: определение — «programming language-agnostic interface description for HTTP APIs». Клик — увеличить.

39OpenAPI 3.2 и OpenAPI 3.1 — не одно и то же

Спецификация развивается, а фреймворки поддерживают её редакции с задержкой.

последняя редакция OAS3.2.1

опубликована 10 сентября 2026 года

генерирует FastAPI 0.1153.1.0

поле openapi в /openapi.json

Минорная версия 3.2 вышла 19 сентября 2025 года (3.2.0), а 10 сентября 2026 года опубликовано исправление 3.2.1. При этом FastAPI по умолчанию генерирует:

{
  "openapi": "3.1.0"
}

Это не означает, что API «неправильный». Framework может поддерживать не самую новую опубликованную версию спецификации.

spec.openapis.org · latestСКРИНШОТ · 15.09.2026
Страница последней редакции: OpenAPI Specification v3.2.1, Published 10 September 2026. Клик — увеличить.

40Swagger и OpenAPI нельзя считать синонимами

Путаница историческая: до 2016 года спецификация называлась Swagger Specification.

формат

OpenAPI Specification

Стандарт описания API. Развивается OpenAPI Initiative. Файл openapi.json или openapi.yaml — документ в этом формате.

инструменты

Swagger

Набор инструментов компании SmartBear, которые работают с документами OpenAPI: редактор, интерфейс документации, генераторы кода.

Документация Swagger прямо разделяет эти понятия: OpenAPI — спецификация, Swagger — инструменты для работы с ней.

41Что входит в экосистему Swagger

Каждый инструмент решает свою задачу, и все читают один и тот же документ OpenAPI.

ИнструментНазначение
Swagger Editorредактирование описания с проверкой в реальном времени
Swagger UIинтерактивная документация в браузере
Swagger Codegenгенерация клиентов и заготовок сервера
Swagger Coreполучение описания из Java-кода
Swagger Parserразбор и валидация документа OpenAPI

Для нашего занятия особенно важен Swagger UI: он читает OpenAPI schema и строит страницу, с которой можно отправлять запросы.

  1. openapi.json
  2. Swagger UI
  3. interactive documentation

42OpenAPI document имеет стандартную структуру

Каждая часть верхнего уровня отвечает за отдельный слой API contract.

упрощённо
openapi:
info:
servers:
tags:
paths:
components:
security:
РазделЧто описывает
openapiредакцию спецификации
infoназвание, версию, владельца API
serversадреса, где API доступен
tagsгруппы операций
pathsадреса и операции
componentsпереиспользуемые схемы
securityтребования аутентификации

Далее разбираем разделы по отдельности.

43API должно представиться

Раздел info отвечает на вопросы, что это за API, какая версия контракта и кто его поддерживает.

openapi.yaml
info:
  title: Service Desk API
  version: 1.0.0
  description: API для работы с обращениями
  contact:
    name: API Team
ПолеОтвечает на вопрос
titleчто это за API
versionкакая версия контракта
descriptionдля чего он нужен
contactкто его поддерживает

Zalando API Guidelines требуют указывать в спецификации title, version, description и контакты владельца API.

44Где доступен API

В OpenAPI можно зафиксировать адреса серверов.

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

  - url: https://stage-api.example.com/api/v1
    description: Staging
OPENAPI
├─ Production
└─ Staging

Это особенно важно при разделении production и test environments: Swagger UI покажет список серверов, и тестовый запрос не уйдёт случайно в боевую систему.

45Endpoints необходимо группировать

Большой API нельзя оставлять одной длинной лентой операций.

Группы называются по предметной области:

Tickets
Users
Authentication
Reports

В FastAPI группа задаётся параметром tags роутера:

app/api/v1/endpoints/tickets.py
router = APIRouter(
    prefix="/tickets",
    tags=["Tickets"],
)
Swagger UI · /docsСКРИНШОТ · 15.09.2026
Swagger UI группирует операции по tag: заголовок группы Tickets с описанием из openapi_tags. Клик — увеличить.

46paths описывает ресурсы

Раздел paths перечисляет адреса, а внутри каждого адреса — допустимые методы.

openapi.yaml
paths:
  /tickets:
    get:
    post:

  /tickets/{ticket_id}:
    get:
    patch:
    delete:
paths
├── /tickets
│   ├── GET
│   └── POST
└── /tickets/{ticket_id}
    ├── GET
    ├── PATCH
    └── DELETE

По paths видна вся структура HTTP interface: какие ресурсы есть и что с каждым можно сделать.

47Каждый method внутри path — отдельная operation

Operation — это описание одного метода на одном адресе.

operation
post:
  summary: Создать обращение
  description: Регистрирует новое обращение
  operationId: createTicket
  tags: [Tickets]
  parameters: []
  requestBody: ...
  responses: ...
ПолеНазначение
summaryкороткое название в списке
descriptionподробное объяснение
operationIdуникальный идентификатор операции
tagsгруппа
parametersпараметры пути, query, заголовков
requestBodyтело запроса
responsesвозможные ответы

operationId должен быть уникальным и желательно стабильным: генераторы SDK превращают его в имя метода, например client.createTicket().

48OpenAPI различает расположение параметров

Параметр может находиться в одном из четырёх мест HTTP-запроса. Поле in указывает, в каком.

HTTP request
GET /api/v1/tickets/{ticket_id}?limit=20
Authorization: Bearer TOKEN
Cookie: session=abc
inПример
pathticket_id
querylimit
headerAuthorization — в OpenAPI описывается через security
cookiesession

Зная место параметра, Swagger UI и сгенерированные клиенты сами собирают правильный запрос.

49Body тоже имеет формальную схему

Для POST /tickets контракт описывает, какое тело клиент обязан прислать.

POST /tickets
{
  "title": "Не работает VPN",
  "description": "Ошибка подключения"
}

OpenAPI описывает:

  • media type;
  • schema;
  • required fields;
  • types;
  • validation;
  • examples.
  1. requestBody
  2. application/json
  3. TicketCreateсхема в components

В учебном проекте title обязателен и содержит от 3 до 120 символов. Запрос без него получит 422 ещё до вызова функции.

50Документируется не только успешный ответ

Клиенту нужно знать все ответы, которые он может получить, иначе он не напишет их обработку.

Для GET /tickets/{ticket_id} недостаточно описать только 200. Контракт должен учитывать:

200OK
404Not Found
422Validation Error

Для защищённого endpoint также:

401Unauthorized
403Forbidden
REQUEST
├─ 200
├─ 401
├─ 404
└─ 422

51Повторяющиеся схемы следует переиспользовать

Вместо копирования одной модели во все operations OpenAPI позволяет создать reusable components.

openapi.yaml
components:
  schemas:
    Ticket:
    TicketCreate:
    TicketUpdate:
    ProblemDetails:
operation
responses:
  "200":
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Ticket"
  1. GET · POST · PATCH
  2. $ref
  3. Ticket schemaописана один раз

Если в Ticket появится поле, оно сразу окажется во всех ответах, которые на неё ссылаются.

52Механизм авторизации должен быть описан

Схема безопасности объявляется один раз в components и подключается к операциям.

Bearer authentication
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

После этого документация показывает кнопку Authorize, и Swagger UI сам передаёт заголовок Authorization в запросах.

Zalando API Guidelines показывают Bearer security scheme в OpenAPI как основной способ защиты endpoints.

  1. CLIENT
  2. Authorization: Bearer TOKEN
  3. API

53Схема отвечает «что допустимо», example — «как это выглядит»

Описание типа полезно, но пример с настоящими данными понимается быстрее.

schema
title:
  type: string
  minLength: 3
example
{
  "title": "Не работает VPN"
}
SchemaExample
string"Не работает VPN"
string, format: date-time"2026-09-15T17:30:00Z"
enum: open, in_progress, closed"open"

Хороший контракт содержит реальные и осмысленные examples, а не "string" в каждом поле.

Кадр крупным планом