“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
- Martin Fowler
What is Swagger ?
Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. The goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters, and models are tightly integrated into the server code, allowing APIs to always stay in sync.
Why is Swagger useful?
The Swagger framework simultaneously solves server, client, and documentation/sandbox needs.
With Swagger's declarative resource specification, clients can understand and consume services without knowledge of server implementation or access to the server code. The Swagger UI framework allows both developers and non-developers to interact with the API in a sandbox UI that gives clear insight into how the API responds to parameters and options.
Swagger happily speaks both JSON and XML, with additional formats in the works.
How to Enable Swagger in your Spring Boot Web Application ?
Step 1 : Include Swagger Spring MVC dependency in Maven
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>0.8.8</version>
</dependency>
Step 2 : Create Swagger Java Configuration
- Use the
@EnableSwagger
annotation. - Autowire
SpringSwaggerConfig
. - Define one or more SwaggerSpringMvcPlugin instances using springs
@Bean
annotation.
[gist https://gist.github.com/saurzcode/9dcee7110707ff996784/]
Step 3 : Create Swagger UI using WebJar
<repository>
<id>oss-jfrog-artifactory</id>
<name>oss-jfrog-artifactory-releases</name>
<url>http://oss.jfrog.org/artifactory/oss-release-local</url>
</repository>
<dependency>
<groupId>org.ajar</groupId>
<artifactId>swagger-spring-mvc-ui</artifactId>
<version>0.1</version>
<scope>compile</scope>
</dependency>
Verify the API Configuration at - http://localhost:8080/api-docs
You can see the Swagger API Docs at http://localhost:8080/index.html
[caption id="attachment_674" align="aligncenter" width="640"] Swagger API Doc[/caption]
Complete project is available at GitHub.
https://github.com/saurzcode/saurzcode-swagger-spring/
References :
You may also like :-
Hi I tried to run your example but I am getting exactly the same problem in my project using the spring mvc version over 6.6 . The api result is :
ReplyDelete{"apiVersion":"1.0","swaggerVersion":"1.2","apis":[{"path":"/default/hello-controller","description":"Hello Controller"}],"info":{"title":"SaurzCode API","description":"API for Saurzcode","termsOfServiceUrl":"Saurzcode API terms of service","contact":"mail2saurzcode@gmail.com","license":"Saurzcode API Licence Type","licenseUrl":"Saurzcode API License URL"}}
Swagger website say this when I paste my url : Unable to read api 'hello-controller' from path http://localhost:8080/api-docs.json/default/hello-controller (server returned undefined)
I am having exactly the same problem in my project and I really don't know how to make it work with a version superior at 6.6
Thank you
I did not get what do you mean when you say doesn't work with spring version superior to 6.6, does that version even exists?
ReplyDelete