Simplified Spring Swagger
Simplified Spring Swagger
Learn more about using Spring Boot Swagger-enabled REST projects.
Join the DZone community and get the full member experience.Join For Free
In this tutorial, we are going to try out a Spring Boot Swagger-enabled REST project and explore how the validation constraints can be utilized automatically for enriching Swagger models.
We are going to refer to https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api and https://spring.io/guides/gs/rest-service/ as starting points.
Start by creating a Maven JAR project. Below, you will see the initial pom.xml:
This is the initial POM.xml.
Now, let's create a small Java bean class.
This is an example Java bean.
Now, let's create a controller.
Above is a sample REST Controller.
Here is an example Swagger configuration:
The Spring Boot application class is shown below:
At this stage, this is what the sample project looks like in Eclipse IDE:
Above are the project contents.
Next, execute the “mvn clean package” from command prompt or terminal. Then, execute “java -jar target\sample-0.1.0.jar.”
You can also launch the application by running the SampleApplication.java class from your IDE.
Now, let's visit the Swagger UI — http://localhost:8080/swagger-ui.html:
Press “Try it out” button. Then, press the execute button. The validation errors are reported below.
Showing below the details for more readability.
Note: For now, try with Parameter content Type of “application/json.”
If you are trying the application/XML parameter content type, adjust manually the <Person> tag to <Person>.
While this is great, what about the validation constraints? Is it possible to bring them out automatically in the Swagger specifications of this sample project?
Now, add the spring-swagger-simplified dependency into the pom.xml:
Then, add this dependency and make one additional change.
Above is the updated main application class
Note: the change is in line 7 and line 9.
Note: in case you used a different package name, please replace "sample” with the package name used just above in the
Stop and relaunch the application.
Revisit the Swagger UI — http://localhost:8080/swagger-ui.html
The difference is in how the model is reported.
Also note that if you are trying the application/XML parameter content type, now there is no need to adjust manually the <Person> tag to <person>. These are some of the additional benefits offered by above spring-swagger-simplified maven jar.
Note: Instead of this approach you can get similar benefits also by using springfox-bean-validators dependency instead of spring-swagger-simplified.
However lets explore spring-swagger-simplified a little more.
In PersonController lets add one more method.
The swagger documentation corresponding to this method will now look like this.
Even parameters show the constraints- see the green text and some of the other differences – eg body vs query- query being definitely the correct representation in this method. Adding springfox-bean-validators does cause the *required and that’s all it offers in this scenario. Using spring-swagger-simplified causes overall better documentation in this scenario.
This was only a brief introduction to the capabilities of this jar. For a more complete understanding of the various features, please try out this more detailed example project with many more fetaures — https://bitbucket.org/tek-nik/simplified-swagger-examples/.
Please also refer to https://dzone.com/articles/doing-more-with-swaggger-and-spring where we discuss global exception handling amongst other details as part II of this article.
- Ensure prerequisites
- If using the Eclipse IDE, we might need to do a Maven update on the project after creating all the files.
- In the SampleApplication main class, make sure you have the correct package name in
@ComponentScan. Avoid typos in the package name there.
- In the Swagger UI, if you are unable to access the “Model” definitions link, it might be because you need to come out of the “try it out “ mode. Click on one or two Cancel buttons that might be visible.
Opinions expressed by DZone contributors are their own.