How to add Swagger OpenAPI specification to spring boot project?

Question

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?

Ali Dehghani · Accepted Answer · 2016-11-14 17:25:47Z

4

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.

edited Nov 14, 2016 at 17:25

answered Nov 14, 2016 at 15:26

Ali Dehghani

48.4k16 gold badges171 silver badges153 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

Orest Over a year ago

Is it possible that swagger-ui will render json from same directory? For example I have swagger-ui in my /static content folder and also I have there swagger.json file.

Ali Dehghani Over a year ago

@Orest It should be possible. You just pass the yml file link to the swagger UI

PAA Over a year ago

@AliDehghani - How can we pass the custom pagination details through Open API 3 UI ?

Collectives™ on Stack Overflow

How to add Swagger OpenAPI specification to spring boot project?

1 Answer 1

3 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

3 Comments

Your Answer

Sign up or log in

Post as a guest

Related