Swagger Editor и описание метода
↑ 1.6 Документация API: Swagger и OpenAPI · ← Предыдущая · → Следующая
Зачем это аналитику и PM
Метод, описанный словами в чате, каждый читает по-своему. Редактор спецификации сразу показывает, собрался ли путь, схема и ответ в один файл, который можно отдать разработке.
План темы
- быстрый старт
- описать метод и модель
- примеры
- проверка спецификации
Объяснение
Swagger Editor — редактор файла OpenAPI. Классический экран делит место надвое: слева текст спецификации, справа собранная страница. Подписи панелей сверьте со своей сборкой. Адрес веб-редактора берите со страницы проекта, не из чужой статьи: хост здесь не записывается.
Как бланк с калькой. Слева вы правите графы. Справа видно, прочитается ли бланк как метод. Красная пометка слева важнее красивой страницы справа.
Метод и модель
Начните с пустого каркаса: версия openapi, заголовок и номер в info. Добавьте путь и метод. У метода — короткое summary, параметры и хотя бы один ответ. Форму тела опишите схемой в components и сошлитесь на неё. Пример значения кладите рядом со схемой или ответом, и пусть он ей подчиняется: лишнее поле в примере, которого нет в свойствах, путает сильнее, чем пустой пример.
Проверка — это не чувство «вроде открылось». Редактор показывает ошибки разбора. Страница справа должна показать ваш метод. Если справа пусто, сначала читают первую ошибку в тексте, а не дописывают второй метод.
Сохранённый файл уходит в задачу или в репозиторий. Черновик только в браузере пропадёт. Секреты в пример не вставляют.
Примеры
Минимум, с которым редактор уже может показать POST. Версия файла — 3.0.3.
openapi: "3.0.3"
info:
title: Example Orders
version: "1"
paths:
/orders:
post:
summary: Создать заказ
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewOrder"
example:
title: example
responses:
"201":
description: Заказ создан
components:
schemas:
NewOrder:
type: object
required: [title]
properties:
title:
type: stringНюансы и подводные камни
- Пример, который не проходит собственную схему, хуже отсутствия примера. Сверьте обязательные поля.
- Редактор в браузере не заменяет ревью. Файл всё равно читает человек, который будет его исполнять.
- Ошибка «не строка YAML» прячет остальные. Чинют сверху.
- Не копируйте в редактор боевой ключ, чтобы «посмотреть, как выглядит заголовок».
Практика
Соберите в редакторе один POST: тело из одного обязательного поля и ответ 201. Добейтесь, чтобы страница справа показала метод без ошибки разбора.
Ожидаемый результат: в файле есть openapi, путь, схема и пример, где обязательное поле заполнено. Файл сохранён у себя, секрета в нём нет.
Вопросы с ответами
С чего начать пустой редактор?
С версии файла, заголовка и одного пути. Не с декоративного описания сервиса на страницу.
Куда класть форму тела?
В
components/schemas, а у метода дать ссылку. Тогда следующий метод возьмёт ту же форму.
Пример обязателен?
Нет, но один согласованный пример снимает вопрос, строка это или число. Он не должен противоречить схеме.
Как понять, что спецификация собралась?
Редактор не показывает ошибку разбора, а справа виден метод с телом и ответом. Устное «откроется у разработчика» не считается.