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

Часть 14 из 15 · слайды 114–120

Практическая работа

Все механизмы собраны в учебном эталоне. Его структура становится образцом для вашей работы.

  1. 114Структура учебного эталона
  2. 115Это не только FastAPI-код
  3. 116Не копируем Service Desk без изменений
  4. 117Контракт является частью repository
  5. 118Диагностика стандарта
  6. 119Контрольные артефакты работы
  7. 120Проверяем понимание, а не память

114Структура учебного эталона

Репозиторий api-standard-template содержит не только код, но и все документы контракта.

api-standard-template/
├── .github/
│   ├── ISSUE_TEMPLATE/
│   ├── workflows/ci.yml, docs.yml
│   ├── CODEOWNERS
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── dependabot.yml
├── app/
├── docs/
│   ├── STANDARDS.md, API_STYLE_GUIDE.md
│   ├── QUICKSTART.md, VERSIONING.md, ERRORS.md
│   ├── SECURITY.md, CONTRIBUTING.md
│   └── adr/
├── openapi/
├── scripts/
├── tests/
├── .spectral.yaml
├── CHANGELOG.md
├── LICENSE
└── README.md
Папка или файлНазначение
app/FastAPI-приложение
docs/правила, политика версий, ошибки, безопасность, ADR
openapi/выгруженный контракт
scripts/выгрузка контракта и сборка страниц ошибок
.github/CI, публикация документации, шаблоны, владельцы кода
docs/STANDARDS.mdисточник каждого правила с цитатой и переводом
tests/поведение endpoints и правила контракта
.spectral.yamlправила линтера

115Это не только FastAPI-код

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

OpenAPISwagger UIReDocBearer schemeProblem DetailspaginationAPI Style Guide
GET /tickets
POST /tickets
GET /tickets/{id}
PATCH /tickets/{id}
DELETE /tickets/{id}
versioning policyADRCHANGELOGcontract testsCISpectraloasdiffETag · If-MatchIdempotency-KeyX-Request-IdCODEOWNERSSTANDARDS.md

Все проверки проходят на версии 1.1.0: 31 тест, export_openapi.py --check и Spectral без замечаний.

116Не копируем Service Desk без изменений

В практической работе вы выбираете собственную предметную область и строите контракт для неё.

Например: Books, Events, Cinema, Warehouse, Delivery, Games, Pets, Music, Reservations.

После выбора необходимо:

  1. определить ресурсы;
  2. спроектировать URI;
  3. выбрать HTTP methods;
  4. определить request/response schemas;
  5. определить status codes;
  6. создать собственный Style Guide;
  7. реализовать API;
  8. проверить OpenAPI;
  9. оформить документацию.
DOMAIN→RESOURCES→CONTRACT→IMPLEMENTATION→VALIDATION

Первый черновик контракта своей области можно проверить здесь же:

мой контрактметод и путь, по одному на строку

117Контракт является частью repository

Изменение контракта оформляется так же, как изменение кода. Git заново не изучаем.

  1. Save
  2. Source Control
  3. Commit
  4. Push
  5. GitHub
  6. GitHub Actions

Сообщение commit должно описывать изменение контракта:

документ
docs(api): define ticket error contract
новая возможность
feat(api): add ticket pagination

Перед commit выполните python scripts/export_openapi.py: иначе CI найдёт расхождение openapi/openapi.json с кодом.

118Диагностика стандарта

Если CI не проходит, двигайтесь от сообщения об ошибке к правилу, а от правила к файлу.

  1. какой именно test или шаг упал;
  2. какой endpoint указан в сообщении;
  3. существует ли operationId;
  4. определён ли success response;
  5. соответствует ли response_model возвращаемым данным;
  6. обновлена ли OpenAPI schema в openapi/;
  7. не нашёл ли oasdiff breaking change в job breaking-changes;
  8. обновлён ли CHANGELOG;
  9. сохранён ли файл;
  10. отправлен ли новый commit.
  1. CI FAIL
  2. RULE
  3. FILE
  4. CONTRACT
  5. FIX
пример сообщения
FAILED tests/test_contract.py::test_every_operation_has_operation_id
AssertionError: GET /api/v1/tickets/{ticket_id} has no operationId

119Контрольные артефакты работы

Для отчёта сохраните ссылки, файлы и скриншоты.

  • ссылка на GitHub repository
  • screenshot Swagger UI
  • screenshot ReDoc
  • screenshot /openapi.json
  • screenshot успешного POST
  • screenshot 404 application/problem+json
  • API_STYLE_GUIDE.md
  • VERSIONING.md
  • CHANGELOG.md
  • ADR
  • OpenAPI YAML/JSON
  • screenshot успешного GitHub Actions run
  • commit hash итоговой версии
Swagger UI · POST /api/v1/ticketsСКРИНШОТ · 15.09.2026
Так выглядит скриншот успешного POST: код 201, тело созданного обращения и заголовок location. Клик — увеличить.

120Проверяем понимание, а не память

Студент должен своими словами объяснить ответы на эти вопросы.

  1. Почему REST и HTTP — не одно и то же?
  2. Почему Swagger и OpenAPI — не одно и то же?
  3. Почему GET /deleteUser является плохим контрактом?
  4. Почему POST и PUT имеют разную семантику?
  5. Почему 401 и 403 нельзя считать одинаковыми?
  6. Почему OpenAPI version и API version — разные вещи?
  7. Что делает breaking change опасным?
  8. Зачем нужен operationId?
  9. Почему Problem Details лучше произвольного JSON?
  10. Зачем API Style Guide, если уже существует OpenAPI?
  11. Что проверяет Spectral?
  12. Почему успешные тесты приложения ещё не гарантируют качественный API contract?

«ПОЧЕМУ?» вместо «ГДЕ КНОПКА?»

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