OpenAPI

OpenAPI и API Documentation

📚 22 вопросовПройти тест →
Лекция

OpenAPI и API Documentation

OpenAPI

OpenAPI и API Documentation

Введение: инструкция к технике 📘

Представь сложный прибор без инструкции. Каждый пользователь пробует наугад. OpenAPI — это инструкция для API: что можно делать и как именно.
💡 Совет: документация нужна не «для галочки», а чтобы не гадать.
✅ Вывод: OpenAPI превращает API в понятную систему.

Проблема → решение

Проблема: без документации команды тратят время на догадки и ошибки. Решение: фиксируем контракт API в OpenAPI‑спецификации и держим её актуальной.
✅ Вывод: единый контракт снижает хаос и ускоряет разработку.

Чем помогает и как работает

OpenAPI помогает всем участникам видеть одно и то же API. Документация становится «истиной», а не набором устных договорённостей.
Как это работает:
  1. Мы описываем API в YAML/JSON файле.
  2. Документ автоматически превращается в UI и подсказки.
  3. Клиенты и сервер синхронизируются по одному контракту.
✅ Вывод: OpenAPI делает API прозрачным и предсказуемым.

Ключевые термины (простыми словами)

  • OpenAPI — стандарт описания API.
  • Spec (спецификация) — файл с описанием всех эндпоинтов.
  • Swagger UI — визуальная документация по файлу OpenAPI.
  • Endpoint — адрес и метод запроса.
  • Schema — описание структуры данных.
  • Request Body — тело запроса.
  • Response — описание ответа и статуса.
  • Security — правила авторизации.
  • Example — пример запроса и ответа.

Самое важное (must‑know)

  • Документация должна совпадать с реальным API.
  • У каждого endpoint должны быть описаны успешные и ошибочные ответы.
  • Нужны примеры запросов и ответов.
  • Авторизация должна быть указана в Security.
  • OpenAPI — это единый контракт для всех команд.
✅ Вывод: это базовые вещи, которые часто спрашивают на интервью.

1. OpenAPI‑файл (спецификация)

Назначение: описать API одним документом. Простыми словами: это «паспорт» API. Аналогия: как инструкция к прибору, где всё расписано.
Пример:
openapi: 3.0.0info:  title: Courses API  version: 1.0.0
🔎 Как это происходит на практике:
  1. Команда пишет файл OpenAPI.
  2. По нему строится документация.
  3. Клиенты используют его как контракт.
Характеристики:
  • ✅ Один источник правды.
  • ✅ Можно валидировать API.
  • ✅ Легко делиться с клиентами.
Когда использовать: всегда для публичного или командного API. ✅ Вывод: spec = основа всей документации.

2. Paths и методы

Назначение: описать все эндпоинты и действия. Простыми словами: список адресов и того, что они делают. Аналогия: меню ресторана с блюдами.
Пример:
paths:  /courses:    get: { ... }    post: { ... }
🔎 Как это происходит на практике:
  1. Добавляем путь /courses.
  2. Описываем методы GET и POST.
  3. Указываем, что возвращается.
Характеристики:
  • ✅ Каждый путь описан явно.
  • ✅ Методы не смешиваются.
  • ✅ Видна структура API.
Когда использовать: для всех адресов API. ✅ Вывод: paths показывают карту API.

3. Schemas (структуры данных)

Назначение: описать форму данных. Простыми словами: какие поля у объекта и как они выглядят. Аналогия: анкета с полями и типами.
Пример:
components:  schemas:    Course:      type: object      properties:        id: { type: string }        title: { type: string }
🔎 Как это происходит на практике:
  1. Описываем структуру объекта Course.
  2. Используем её в ответах.
  3. Клиенты знают, какие поля будут.
Характеристики:
  • ✅ Структуры переиспользуются.
  • ✅ Меньше расхождений.
  • ✅ Типы данных понятны.
Когда использовать: для всех сущностей API. ✅ Вывод: schemas дают точный формат данных.

4. Parameters и Request Body

Назначение: объяснить, что нужно передать в запросе. Простыми словами: какие данные клиент должен отправить. Аналогия: список нужных документов при подаче заявки.
Пример:
parameters:  - name: page    in: query    schema: { type: integer }requestBody:  content:    application/json:      schema: { $ref: "#/components/schemas/Course" }
🔎 Как это происходит на практике:
  1. Описываем query‑параметры.
  2. Описываем тело запроса.
  3. Клиент понимает, что отправлять.
Характеристики:
  • ✅ Запросы становятся однозначными.
  • ✅ Меньше ошибок на клиенте.
  • ✅ Легко валидировать.
Когда использовать: для всех запросов с параметрами и телом. ✅ Вывод: параметры и body = ясные правила входа.

5. Responses и коды ошибок

Назначение: показать, что вернёт сервер. Простыми словами: какие ответы ждать и при каких условиях. Аналогия: «если всё хорошо — зелёный свет, если нет — красный».
Пример:
responses:  "200": { description: OK }  "404": { description: Not Found }
🔎 Как это происходит на практике:
  1. Описываем успешный ответ.
  2. Описываем ошибки (400, 401, 404, 429).
  3. Клиент знает, как реагировать.
Характеристики:
  • ✅ Ошибки не сюрприз.
  • ✅ Тестирование проще.
  • ✅ Клиент знает логику.
Когда использовать: для каждого endpoint. ✅ Вывод: ответы — это договор с клиентом.

6. Security и авторизация

Назначение: описать, как защищён API. Простыми словами: какие ключи или токены нужны. Аналогия: пропуск в офис.
Пример:
components:  securitySchemes:    bearerAuth:      type: http      scheme: bearer
🔎 Как это происходит на практике:
  1. Описываем тип авторизации.
  2. Добавляем его к защищённым эндпоинтам.
  3. Клиенты понимают, что нужно передать.
Характеристики:
  • ✅ Авторизация описана явно.
  • ✅ Безопасность понятна.
  • ✅ Меньше ошибок в интеграции.
Когда использовать: всегда, если API не публичный. ✅ Вывод: security — обязательная часть документации.

7. Примеры запросов и ответов

Назначение: дать быстрые понятные примеры. Простыми словами: показать «как это выглядит» вживую. Аналогия: пример заполненной анкеты.
Пример:
example:  id: "c1"  title: "HTTP Basics"
🔎 Как это происходит на практике:
  1. Добавляем пример тела.
  2. Клиент видит формат данных.
  3. Интеграция идёт быстрее.
Характеристики:
  • ✅ Примеры ускоряют понимание.
  • ✅ Меньше вопросов в чате.
  • ✅ Быстрее тесты и интеграции.
Когда использовать: в каждом важном endpoint. ✅ Вывод: примеры — это быстрый старт.

Сравнение: с OpenAPI и без

Без OpenAPIС OpenAPI
Много устных договорённостейОдин контракт для всех
Трудно тестироватьЛегко валидировать
Ошибки в интеграцииБыстрая интеграция
Документация устареваетДокументация живая

Часто спрашивают на собеседованиях

  • Чем OpenAPI отличается от Swagger?
  • Что должно быть в responses обязательно?
  • Как описывать авторизацию?
  • Почему спецификация должна совпадать с API?
  • Зачем нужны примеры в документации?
✅ Вывод: эти вопросы проверяют практику документации.

Типичные ошибки

Ошибка 1: Документация не обновляется

❌ Неправильно: API меняется, а spec остаётся старым.
✅ Правильно: обновлять OpenAPI при каждом изменении.
Почему: иначе контракт ломается.

Ошибка 2: Нет ошибок в responses

❌ Неправильно: описан только 200.
✅ Правильно: описывать 400/401/404/429.
Почему: клиент должен знать все сценарии.

Ошибка 3: Нет примеров

❌ Неправильно: только схемы без примеров.
✅ Правильно: примеры запросов и ответов.
Почему: примеры ускоряют интеграцию.

Ошибка 4: Нет security

❌ Неправильно: авторизация «где‑то в тексте».
✅ Правильно: securitySchemes в OpenAPI.
Почему: иначе клиенты ошибаются.

Ошибка 5: Разные форматы данных

❌ Неправильно: ответ отличается от schema.
✅ Правильно: schema = реальный формат.
Почему: иначе тесты и SDK ломаются.

Ошибка 6: Нет единого источника

❌ Неправильно: docs в Confluence, а API другое.
✅ Правильно: OpenAPI = единственный контракт.
Почему: уменьшает хаос.

Best Practices

  • Держи спецификацию рядом с кодом и обновляй при изменениях.
  • Всегда описывай ошибки и коды ответов.
  • Добавляй примеры запросов и ответов.
  • Используй схемы компонентов повторно.
  • Документируй авторизацию в securitySchemes.
  • Проверяй, что API соответствует spec.

Заключение

OpenAPI — это контракт, по которому живёт API. Он даёт прозрачность, порядок и быстрые интеграции. Если документация актуальна — команда работает уверенно.
✅ Вывод: хорошая документация — это часть качества продукта.
🎯

Проверьте знания

Закрепите материал — пройдите тест по теме «OpenAPI и API Documentation»

Пройти тест →