Swagger-Open API to Spring Boot 3 Application(Web Flux)

Documenting a REST API is essential to make it user-friendly and accessible. With the help of the OpenAPI specification and Swagger, creating comprehensive documentation is a breeze.

What is Swagger?

Swagger is a toolset that allows developers to design, build, and document RESTful APIs. It provides an easy-to-use interface for exploring and testing the API. Swagger also allows developers to generate documentation automatically from the OpenAPI specification.

What is OpenAPI?

The OpenAPI specification, previously known as the Swagger specification, is a standard language-agnostic interface to describe RESTful APIs. It allows developers to describe the different endpoints of the API, the operations that can be performed on each endpoint, and the data models used by the API. This specification can be used to generate documentation, generate client libraries, and perform automated testing.

Documenting an API using OpenAPI and Swagger is an efficient and standardised way of creating comprehensive documentation for your API. With that said, let’s dive into how to add Swagger to your Spring-Boot 3 application.

Step 1: Add the Dependencies

The first step is to add the necessary dependencies to your project. In this case, we need to add the following dependencies:

 implementation("org.springdoc:springdoc-openapi-starter-webflux-ui:2.0.4")

The implementation of “org.springdoc:springdoc-openapi-starter-webflux-ui:2.0.4” provides an easy way to add the OpenAPI specification and Swagger UI to your web application built with Spring WebFlux framework. This means that you can document and visualize your APIs with Swagger UI using annotations, without the need for manual configuration.

Step 2: Access Swagger

Finally, you can access Swagger UI by navigating to http://localhost:8080/swagger-ui/index.html. This will display the Swagger UI interface, which allows you to explore and test your API endpoints.

Step 3: Configure Swagger
To configure Swagger in your Spring Boot 3 application, you have two approaches: adding the @OpenAPIDefinition annotation to the main class of your application or creating a SwaggerConfiguration class.

Approach 1: Adding the @OpenAPIDefinition Annotation to the Main Class,
open the main class of your Spring Boot application.

• Add the @OpenAPIDefinition annotation to the class. This annotation is used to define the global OpenAPI settings.
• Optionally, you can provide additional information about your API by setting properties of the @OpenAPIDefinition annotation, such as info or tags.

@OpenAPIDefinition annotation

Approach 2: Creating a SwaggerConfiguration Class

• Create a new class, such as SwaggerConfiguration, in your project.
• Annotate the class with @Configuration to indicate that it provides bean definitions.

SwaggerConfiguration.kt (Configuration Class)

Remember to include the necessary import statements for the annotations used in the code.

By following either of these approaches, you can configure Swagger in your Spring Boot 3 application and generate comprehensive documentation for your REST API using the OpenAPI specification.

Step 4: Configure Paths
To configure paths for Swagger in your Spring Boot 3 application, you can use the application.yml (or application.properties) file. Here's an example of how to configure the paths:

application.yml

• springdoc.swagger-ui.enabled is set to true to enable the Swagger UI.
• springdoc.swagger-ui.path is the URL path where Swagger UI will be accessible. In this example, it is configured as v1/your-application/swagger-ui.html.
• springdoc.api-docs.path is the URL path for the OpenAPI specification JSON. In this example, it is configured as /v1/your-application-docs.

You can customize the paths according to your project’s requirements. Once you have made the configuration changes, start or restart your Spring Boot application, and the Swagger UI will be accessible at the specified path.

Please note that you should replace your-application in the path configurations with the appropriate name or identifier for your application or API.

By configuring the paths, you can access the Swagger UI and the OpenAPI specification at the specified URLs, making it easy for users to explore and test your API.