Нет необходимости создавать коллекцию HTML, JavaScripts и CSS-ресурсов из файлов .yml или .json. Просто передайте файл YAML / JSON на сервер, на котором запущен пользовательский интерфейс Swagger, и пользовательский интерфейс Swagger будет динамически генерировать красивую документацию из этих совместимых со Swagger API. Пример petstore должен дать вам представление.
Вы можете использовать механизм сборки (сервер CI / CD или что-то еще), например Jenkins, для автоматизации процесса публикации документации. Например, каждый репозиторий REST API должен предоставлять хотя бы один из этих .yml или .json файлов (которые, кстати, генерируются редактором Swagger). Затем после каждого нажатия в этот репозиторий Jenkins будет получать эти .yml или .json файлы и загружать их на ваш сервер документации, где пользовательский интерфейс Swagger запущен и работает.
Разработчики REST API могут поделиться ссылкой на документацию API с разработчиками клиентов, а также могут быть уверены, что каждое изменение в файлах .yml или .json будет отражено в документации. Им просто нужно продвигать изменения. Поскольку вам необходимо поддерживать эти API-интерфейсы, совместимые с Swagger, я лично предлагаю использовать файл .yml просто потому, что он более читабельный.
person
Ali Dehghani
schedule
14.11.2016
