Зачем нужен Swagger/OpenAPI?

Question

[wawa]

Swagger/OpenAPI - это спецификация, т.е. просто формат описания REST API.
Но как это использовать?
1) REST фреймворк должен сам генерировать yaml-файл, описывающий API?
2) Или наоборот, пишем руками yaml-файл, на основе которого генерится какая-то часть кода?
Например необходимость этой спеки в сценарии (1) вообще сомнительна - мне же не yaml-файл нужен, а отрендеренная в браузере страничка доков - зачем посредник в виде этой спеки?
Какой вообще workflow использования?

Comments

[NaName]

пишешь yaml файл - документация готова. на основании yaml файла (документации) пишешь API. для питона помню была какаято либа, которая связывала приложение flask и yaml файл, проверяла все ли ссылки валидны и тд. не нужно было указывать урл каждого метода API в коде приложения. урл и метод для API связывались через эту либу. не знаю как в других языках. в Swagger документации можно найти урл, на котором находится сгенерированная человеко-читаемая документация API, основанная на yaml файле. на этом же урле будут указаны все нужные параметры, формат ответа и можно будет попробовать послать запрос к API с кастомными значениями параметров

[wawa]

NaName, в бест практис рекомендуют в GET запросах юзать поле "fields", которое указывает какие поля нужно вернуть: site.ru/api/users?age=22&sex=f&fields=name,salary - где age и sex это фильтр, а fields - интересующие поля. Swagger спека это как-то учитывает?
Вы пишите, что в yaml указывается и формат ответа. Swagger спека это учитывает (что могут вернуться не все поля из-за "fields")?

[NaName]

да учитывает (фильтр, интересующие поля). да учитывает (формат ответа). https://swagger.io/docs/specification/basic-structure/ жирными буквами responses (примерно в середине скролла) примерный образец описания некоторого endpoint. может станет немного яснее

[wawa]

NaName, не вижу как исключать возвращаемые поля. Может тыкнуть где это?

[NaName]

wawa, https://swagger.io/docs/specification/describing-r... жирными буквами anyOf, oneOf. в зависимости от ответа будет использоваться разный набор полей. в схеме объявляем обязательные поля, возможные поля и тд. т.е. api отдает такой json (грубо)
{field_1: 1, field_2: 2}
если есть соответствующая схема, то будет отображаться 2 поля. если есть только одна схема с этими 2 полями и еще одним полем (field_3) то будут отображаться 2 поля (всё по прежнему) + 1 поле с null value
про схемы https://github.com/OAI/OpenAPI-Specification/blob/... ctrl+f schema object

Answer 1

[unchase]

Есть несколько способов или подходов:

1) Да, есть библиотеки (фреймворки), которые генерируют файл спецификации по коду, а уже по этому файлу - документацию, например, Swashbuckle, NSwag и пр. В этом случае разработчику достаточно использовать специальные средства фреймворка (такие как аннотации) и обычные комментарии к коду, по которым и будет сгенерирован файл спецификации и уже после документация по нему. То есть этот файл - не посредник, а необходимый "артефакт", без него вы все равно не сгенерируете документацию.

Кроме того, по этому сгенерированному файлу уже можно будет автоматически генерировать код клиента на различных языках программирования. Например, для C# и TypeScript, используя Unchase OpenAPI (Swagger) Connected Service в IDE Visual Studio 2017/2019, можно легко это сделать (статья на medium.com).

2) Другой подход подразумевает сначала создание файла спецификации для REST API (в yaml или json), а после генерации из него и кода клиентов, и кода контроллеров сервиса (например, и то, и другое можно сделать с помощью Unchase OpenAPI (Swagger) Connected Service), а также документации. При этом сам файл не обязательно писать руками, есть конструкторы для OpenAPI сервисов.

Но писать руками файл спецификации удобно в том случае, когда создание сервиса на этапе планирования. Если сервис уже существует, то удобней пользоваться фреймворками и конструкторами.