CODEWITHSUNDEEP
restswaggerswagger-uiopenapi
Orest
Orest

Reputation: 6748

How to 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. Also, I can see in http://editor.swagger.io/ that it could be rendered to .html file.

My question is - how can I generate static .html pages from .json/.yml files? Is there any tutorial for spring boot application? Should I somehow set .json/.yml files to swagger configuration and get .html file with documentation?

Upvotes: 4

Views: 4539

Answers (1)

Ali Dehghani
Ali Dehghani

Reputation: 48193

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 can 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.

Upvotes: 4

Related Questions