Swagger in Spring Boot
Overview
In the past few years, web API development has grown drastically. More and more public APIs have been released each year. It's important for API providers to document the API so that consumers can interpret and understand what is the API's purpose and how to use it. OpenAPI specification solves the problem by providing language-agnostic and vendor-neutral specifications.
Introduction
What is OpenAPI Specification?
The OpenAPI Specification is a standard format to define the structure and syntax of REST APIs. OpenAPI documents are machine- and human-readable, enabling anyone to easily determine how each API works.
The specification is maintained by the OpenAPI Initiative. As of this writing latest version of the spec is 3.1.0.
Why Swagger?
There always needs to be clarity between OpenAPI vs. Swagger. The easiest way to understand the difference is:
- OpenAPI = Specification
- Swagger = Tools for implementing the specification
Like SLF4J specification and different logging frameworks implement the specification the same way open API specification is implemented by swagger.
Swagger provides a set of tools and libraries to work with the specification. Some of the useful tools are:
- Swagger Editor: Swagger Editor facilitates us to edit OpenAPI specifications in YAML/JSON inside your browser to provide a nice real-time preview.
- Swagger UI: Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from an OAS-compliant API.
- Swagger Codegen: It generates an API client library from the specification document to interact with the API without writing much code.
Enable Swagger in Spring Boot Application
There are a few steps to enable and configure in spring boot.
Add Dependency
We need to add the below maven dependency.
Configure Swagger without Spring Security
Configure Swagger with Spring Security
If the application uses spring security, the configuration will be changed a bit.
SwaggerConfig.java
SecurityConfig.java Update security configuration to allow all swagger-related endpoints.
On line number 4, we have allowlist paths we want to allow unauthorized access. On line number 26, allowlist paths are configured to allow without authorization.
Verification
Run the application and hit the endpoint http://app-root/swagger-ui/index.html.
The loaded page will list all the APIs and actions to interact with them. But the description of what API does needs to be included.
We will add a description to the /register API.
The API section will be updated on swagger UI with the required details added to the endpoint.
What we have just seen in swagger UI is not the intent of swagger. Swagger UI is one component that allows us to interact with and test API locally. Swagger's purpose is to provide clients with API documentation in JSON or YAML format.
To generate the API doc hit the endpoint http://app-root/v3/api-docs. It should return the corresponding specification JSON in the OpenAPI spec format.
Once spec doc is available, it can interact with different swagger-provided tools.
The source code for this article is available at GitHub.
Take your Java development to the next level with our Spring Boot course. Enroll and bring your projects to life using the power of Spring Boot.
Conclusion
In this article, we have covered.
- Importance of API documentation
- What is OpenAPI specification.
- What is swagger and its role in providing documentation.
- Integrate spring with swagger with and without spring security.