Комментарии 17
Удобно генерацию документации совместить с авто-тестами API. У вас всегда будет целостный проект с актуальными доками.
в .net core скоро эту версию завезут?
все хорошо, пока с КОРСА не столкнешся… ну и так, местами нюансы есть, но для описания апи конечно — маст юз
У нас в cloud.redhat.com OpenAPI используется очень широко. Мы пишем спецификации для каждого сервиса в отдельном openapi.json. Могу сказать, что в начале, когда API небольшой, то спецификацию можно и руками писать. Однако, с ростом сервиса это делать становится всё труднее, например. Я для себя нашёл прекрасный инструмент для визуального редактирования спеки studio.apicur.io.
Не могу понять, почему для описания спецификации они выбрали JAML/JSON, а не XML? С моей точки зрения XML был бы удобней, т.к. позволяет разделить описание структуры документа от метаданных.
Посмотрел сейчас Swagger editor — спецификация отображается только в YAML, а сохранить или загрузить можно только документ в форматах YAML и JSON. Это онлайн версия редактора. Возможно, есть десктоп версия редактора, где можно работать с XML?
вот, не оно часом? swagger.io/docs/specification/data-models/representing-xml
Поделюсь своим опытом использования Swagger — вдруг кому пригодится.
Вместо Swagger Editor использую Stoplight Studio:
В качестве языка использую Python. Пробовал пользоваться родным Swagger Codegen — в определённых ситуациях код генерится с синтаксическими ошибками (точно не помню, кажется если задавать Enum'ы). Использовал последний образ кодгена из dockerhub и валидную схему.
В итоге перешёл на OpenAPI Generator — там нет таких проблем. Много различных вариантов использования. Есть даже плагин для PyCharm, хотя я предпочитаю использовать образ с докерхаба. Синтаксис использования CLI инструмента мало отличается от CLI Swagger Codegen.
Вместо Swagger Editor использую Stoplight Studio:
- Есть бесплатная версия
- Есть десктопные версии под распространённые оси
- Поддерживает астосохранение (никакой копипасты из/в Swagger Editor или открытий/сохранений через диалоговые окна)
- Поддерживает работу с несколькими файлами (через $ref)
В качестве языка использую Python. Пробовал пользоваться родным Swagger Codegen — в определённых ситуациях код генерится с синтаксическими ошибками (точно не помню, кажется если задавать Enum'ы). Использовал последний образ кодгена из dockerhub и валидную схему.
В итоге перешёл на OpenAPI Generator — там нет таких проблем. Много различных вариантов использования. Есть даже плагин для PyCharm, хотя я предпочитаю использовать образ с докерхаба. Синтаксис использования CLI инструмента мало отличается от CLI Swagger Codegen.
А я правильно понимаю, что swagger-generator для spring до сих пор поддерживает в генерируемых контроллерах только springfox и не умеет springdoc?
Вот такой PR навшел github.com/OpenAPITools/openapi-generator/pull/6306
Вот такой PR навшел github.com/OpenAPITools/openapi-generator/pull/6306
Я правильно понимаю, что при использовании разных инструментов или описания в json, yaml, документация всегда будет отставать от кода, а вслучае изменений в нем может вообще не соответствовать? Если же использовать генерацию через аннотации, то документация менее подвержена устареванию, но строчек кода в условном контроллере они займут прилично?
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Swagger (OpenAPI 3.0)