Hello Everyone,
This article is for college students who want to know about swagger (open-api).
Swagger is a library that sets a standard way to write documentation. It’s a common way of writing REST API documentation, so every new or existing developer, tester, and product manager can understand API’s workings (Ins and Outs). It includes almost everything like HTTP requests, HTTP responses, parameters, error codes, etc.
Suppose you are working on a product and creating multiple APIs. To demonstrate APIs work to product owners or other business heads including other teams who want to use APIs, we can use swagger-ui. Swagger-UI provides an awesome visualization. It is a fast and easy-to-use tool.
Swagger auto-generates documents for your APIs by providing minimal configuration and information.
It’s quite handy to use, even a non-technical person can use it and get to know the workings of APIs. It is a widely accepted tool worldwide. Swagger uses OpenAPI specifications that are widely adopted and also open source.
On today’s date (10-Octobber-2023), swagger is available with two versions version-1 and version-2. Version 1 does not support spring-boot 3 instead we use version 2 for spring-boot 3.
To enable swagger-ui in your spring-boot project, we must add a dependency “springdoc-openapi-ui” in the POM file. “Spring-boot 1/2” and “Spring-boot 3” use open-API versions 1 and 2 respectively.
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
</dependency>
Apart from the above dependency, we also need to add the “Spring-boot-starter-validation” dependency. It needs to be added because of the Validation implemented in the project and its complete discussion is in another article.
We also need to add URLs in the spring security configuration if implemented. URLs are like “/v2/api-docs“, “/v3/api-docs“, “/v3/api-docs/**“, “/swagger-ui.html“, etc. When you type the URL (http://localhost:8080/swagger-ui.html) you use see below image in your browser. It shows GET, POST, PUT, and DELETE whatever your REST-API have added to the project. If not added, It shows nothing. 
Apart from REST-APIs, also provides schemas/model details. Swagger scans all the objects which we are using in the project. We can customize swagger-ui defaults by providing configuration details as per our requirements.
Add Open API configuration:
- Create one Java file in the config package, if don’t have please add a config package. Java File name “OpenApiConfig.java” and add annotations @OpenAPIDefinition, @SecurityScheme, @SecuritySchemes, etc.
- OpenAPIDefinition itself has several properties like Info (title, description, contact, license, server, etc), and security. We can add as many server details as Local, PROD, and UAT and can decide on which environment we want to test the application. Security attribute provides global authentication for all REST APIs.
- SecurityScheme has several property details like name, description, scheme, type, bearerFormat, and in. Using these properties, we provide security config details. In the same way, we also have SecuritySchemes. So, we can add multiple security schemes for some APIs we use bearer tokens and for some, we use basic auth. To implement different security requirements, we have to use @SecurityRequirement on controllers. But if we apply global security implementation for all REST APIs then the security attribute is sufficient in OpenApiConfig.
- Another annotation @Tag on controllers to give a name in swagger-ui. @Operation on REST APIs to provide information like API responses using multiple annotations @ApiResponse like 200 OK or 4XX client-side errors.
Swagger comes with multiple features which need to be explored.
Reference:
https://springdoc.org/v1/
https://springdoc.org/