Swagger (OpenAPI 3.0)

[kolbaskinmax]

Удобно генерацию документации совместить с авто-тестами API. У вас всегда будет целостный проект с актуальными доками.

[sojey80135]

в .net core скоро эту версию завезут?

[nkF7]

Для .net core уже существует (https://github.com/domaindrivendev/Swashbuckle.AspNetCore), не тестил, но репа выглядит как актуальная

[iZombieBl]

Visual Studio при создании проектов на .Net Core 5.0 предлагает использовать Swagger. Всё работает из коробки.

[nkF7]

Спасибо, буду знать

[AlexPancho]

все хорошо, пока с КОРСА не столкнешся… ну и так, местами нюансы есть, но для описания апи конечно — маст юз

[quarckster]

У нас в cloud.redhat.com OpenAPI используется очень широко. Мы пишем спецификации для каждого сервиса в отдельном openapi.json. Могу сказать, что в начале, когда API небольшой, то спецификацию можно и руками писать. Однако, с ростом сервиса это делать становится всё труднее, например. Я для себя нашёл прекрасный инструмент для визуального редактирования спеки studio.apicur.io.

[Bakuard]

Не могу понять, почему для описания спецификации они выбрали JAML/JSON, а не XML? С моей точки зрения XML был бы удобней, т.к. позволяет разделить описание структуры документа от метаданных.

[AlexPancho]

в Едиторе есть возможность сохранять и загружать из XML, просто по умолчанию — JSON

[Bakuard]

Посмотрел сейчас Swagger editor — спецификация отображается только в YAML, а сохранить или загрузить можно только документ в форматах YAML и JSON. Это онлайн версия редактора. Возможно, есть десктоп версия редактора, где можно работать с XML?

[AlexPancho]

вот, не оно часом? swagger.io/docs/specification/data-models/representing-xml

[Bakuard]

Спецификация Open API 3 поддерживает формат XML. Но речь идет об ИНСТРУМЕНТЕ — Swagger editor.

[Tarolrr]

Поделюсь своим опытом использования Swagger — вдруг кому пригодится.

Вместо Swagger Editor использую Stoplight Studio:

• Есть бесплатная версия
• Есть десктопные версии под распространённые оси
• Поддерживает астосохранение (никакой копипасты из/в Swagger Editor или открытий/сохранений через диалоговые окна)
• Поддерживает работу с несколькими файлами (через $ref)

В качестве языка использую Python. Пробовал пользоваться родным Swagger Codegen — в определённых ситуациях код генерится с синтаксическими ошибками (точно не помню, кажется если задавать Enum'ы). Использовал последний образ кодгена из dockerhub и валидную схему.
В итоге перешёл на OpenAPI Generator — там нет таких проблем. Много различных вариантов использования. Есть даже плагин для PyCharm, хотя я предпочитаю использовать образ с докерхаба. Синтаксис использования CLI инструмента мало отличается от CLI Swagger Codegen.

[mgramin]

А я правильно понимаю, что swagger-generator для spring до сих пор поддерживает в генерируемых контроллерах только springfox и не умеет springdoc?
Вот такой PR навшел github.com/OpenAPITools/openapi-generator/pull/6306

[nkF7]

Да, все верно

[Trinion]

Я правильно понимаю, что при использовании разных инструментов или описания в json, yaml, документация всегда будет отставать от кода, а вслучае изменений в нем может вообще не соответствовать? Если же использовать генерацию через аннотации, то документация менее подвержена устареванию, но строчек кода в условном контроллере они займут прилично?

[nkF7]

Да, все верно вы понимаете. Данные да подхода отличаются и иммеют как свои плюсы так и минусы к сожалению