Orest Orest - 22 days ago 9
reST (reStructuredText) Question

Add Swagger OpenAPI specification to spring boot project

I found this project https://github.com/OAI/OpenAPI-Specification
As I understood we can write documentation in

.json/.yml
files. As I can in http://editor.swagger.io/ it could be rendered to
.html
file easily.

So my questions - how I can generate static .html pages from those files? Is there any tutorial for spring boot application? Should I somehow give
.json/.yml
files to swagger configuration to get ready
.html
file with documentation?

Answer

There is no need to generate collection of HTMLs, JavaScripts and CSS assets from the .yml or .json files. Just pass the YAML/JSON file to a server running the Swagger UI and Swagger UI will dynamically generate beautiful documentation from those Swagger-compliant APIs. The petstore example should give you the idea.

You can use a build engine (CI/CD server or whatever) like Jenkins to automate the documentation publishing process. For example, each REST API repository should provide at least one of these .yml or .json files (which by the way are generated by the Swagger Editor). Then after each push to that repository, Jenkins will get those .yml or .json files and upload them to your Documentation server where the Swagger UI is up and running.

REST API developers can share the API documentation link with client developers and also be confident that each change in the .yml or .json files will be reflected in the documentation. They just need to push the changes. Since you need to maintain those Swagger-compliant APIs, I personally suggest to use the .yml file, simply because it's more readable.