Configuring Auto Generation of Swagger Documentation
A Swagger is an open-source tool. It builds around the OpenAPI Specification that helps developers to design, build, document, and consume RESTful APIs. It is the most popular API documentation format for RESTful Web Services. It provides both JSON and UI support. JSON can be used as a machine-readable format, and Swagger-UI is for visual display, which is easy for humans to understand by just browsing the API documentation. The main Swagger tools are:
- Swagger UI: It creates interactive API documentation.
- Swagger Editor: It is a browser-based editor where we can write OpenAPI specifications.
- Swagger Codegen: It generates server stubs (API implementation stub), and client libraries form an OpenAPI specification.
An OpenAPI Specification (formerly known as Swagger Specification) is an API documentation format for REST APIs. An Open API file allows us to describe our entire API, including:
- Available endpoints (/users) and operations on each endpoint (GET /users, POST /users).
- Operation parameters for each operation.
- Authentication methods.
- Contact information, license, the term of use and other information
Let’s generate Swagger documentation for our RESTful services.
Step 1: Open pom.xml and add springfox-swagger2 dependency.
Add another dependency springfox-swagger-ui
Now we need to configure Swagger.
Step 2: Create a class with the name SwaggerConfig.java and write the following code.
Docket: A builder that is intended to be the primary interface into the swagger-Spring MVC Framework. Docket provides sensible defaults and convenience methods for configuration.
Step 3: Run the application.
Step 4: Open the browser and type the URI http://localhost:8080/v2/api-docs
It shows the complete documentation in JSON format, as shown in the following image. It is not much easy to read and understand. Swagger has provided it to be used in other systems like API management tools that offer functionality like API gateways, API caching, API documentation, etc.
If we want to share the documentation of web service with customers, we can share this JSON file.
Now type the URI http://localhost:8080/swagger-ui.html in the browser. It shows the documentation of the services that we have created.
We can also expand the services to see which operations are present in service. In the following image, we have expanded user resource service.