How-To : Generate Restful API Documentation with Swagger ?
What is Swagger?
“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
– Martin Fowler
Swagger is based on OPEN API specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services by effectively mapping all the resources and operations associated with it. 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 framework simultaneously solves the server, client, and documentation/sandbox needs.
With Swagger’s declarative resource specification, clients can understand and consume services without the 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 a clear insight into how the API responds to parameters and options.
It happily speaks both JSON and XML, with additional formats in the works.
Now let’s see a working example and how do we configure Swagger, to generate API documentation of our sample REST API created using Spring Boot.
How to Enable Swagger in your Spring Boot Web Application?
If you are one of those lazy people who hate reading the configurations, download the complete working example here , otherwise, go on –
Step 1: Include Swagger-SpringMVC dependency in Maven
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>0.8.8</version>
</dependency>Step 2: Create a Swagger Java Configuration
- Use the
@EnableSwaggerannotation. - Autowire
SpringSwaggerConfig. - Define one or more SwaggerSpringMvcPlugin instances using springs
@Beanannotation.
Step 3: Create Swagger UI using WebJar
For using web jar dependency add, following repository and dependency, which will auto-configure swagger UI for you.
<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>
That’s it. Now run the Application.java as a java application in your IDE, and you will see the application running in embedded tomcat/jetty server running at default port 8080.
Verify the API Configuration by pointing your browser at – http://localhost:8080/api-docs
{"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":"[email protected]","license":"Saurzcode API Licence Type","licenseUrl":"Saurzcode API License URL"}}And finally, you can see the Swagger API Docs and test the APIs at http://localhost:8080/index.html
Swagger: API Doc for RESTful API
Also, please note that default URL in web jar files is – http://petstore.swagger.wordnik.com/api/api-docs So you might see an error like this, “Can’t read from the server. It may not have the appropriate access-control-origin settings.”
Solution: Just replace the URL [http://petstore.swagger.wordnik.com/api/api-docs] on-screen with [http://localhost:8080/api-docs] and you will see UI as above.
Again, complete project is available at GitHub.
https://github.com/saurzcode/saurzcode-swagger-spring/
References :
Do write back in comments, if you face any issues or concerns !!
You may also like:-
- Setting up Realtime Analytics over logs using ELK Stack
- Top 10 Hadoop HDFS Shell Commands.
- Hive – SORT BY, DISTRIBUTE BY vs CLUSTER BY
