Swagger Implementation for Webflux functional programming model

1. Overview

What Is Swagger?

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs. It helps in building an interactive API documentation and as a testing tool for API’s. It also provides an UI to test your API’s.

What is OpenAPI?

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs.

An OpenAPI file allows you to describe your entire API including:

• Available endpoints (/employees , /job)
• Operations on each endpoint (GET /employees, POST / employee, PUT /employee, DELETE /employee)
• Operation parameters Input and output for each operation
• Headers and its Default Value
• Description for API’s

2. Scope

This article is mainly focused on integrating swagger with API’s using spring Webflux functional programming model.The creation of Webflux project is not in scope of this article.For more information on creating a project, check out the documentation available at this link.

We have used springdoc-openapi-webflux dependencies for integrating with swagger for our Webflux project.

3. Adding the Maven Dependency

The following two libraries must be included to enable Springdoc support for a reactive application based on Spring WebFlux.

<dependency>
  <groupId>org.springdoc</groupId> 
  <artifactId>springdoc-openapi-webflux-core</artifactId>
  <version>1.4.3</version>
</dependency>
<dependency>
  <groupId>org.springdoc</groupId> 
  <artifactId>springdoc-openapi-webflux-ui</artifactId>
  <version>1.4.3</version>
</dependency>

The same or higher dependency version can be used as per the requirement.

NOTE: The SpringDoc OpenAPI library has more support for Spring reactive API’s built using WebFlux as compared to the SpringFox library. We can also have both SpringFox and Springdoc-openapi enabled as per requirement.

4. Integrating OpenAPI Into the Project

4.1. @OpenAPIDefinition

Annotation to add general application/api information (contact info, version, description etc), tags, servers, security and externalDocs.

@Info: Annotation is used to populate the Info section of the OpenAPI document.The info section contains API information: title, description (optional), version.

• title-Application/Api name.
• description- Extended information about API.
• version- specifies the version of API

info also supports other keywords for contact information, license, terms of service, and other details.

NOTE: This blog contains element required for a basis use case. All the supported elements in @OpenAPIDefination annotation can be found here.

The following code example adds the annotation to the main class with information about the application and specific method for API information.

@SpringBootApplication
@OpenAPIDefinition(info = @Info(title = "Swagger Demo", version = "1.0", description = "Documentation APIs v1.0"))
public class SwaggerDemoApplication {
//..
}

The Swagger UI header after adding the title, version and description to application will look similar to the figure below.

Header Section of Swagger UI

4.2. @RouterOperation

Since version v1.3.8, the support of functional endpoints has been added. Two main annotations have been added for this purpose: @RouterOperations and @RouterOperation.

Only REST APIs with the @RouterOperations and @RouterOperation can be displayed on the swagger-ui.

@RouterOperation : This annotation should be used if the Router bean contains one single route related to the REST API.It can reference-

• spring Bean (beanClass property)
• path(API Path)
• Request Method(GET,POST etc)
• The underlying method (beanMethod property)

Springdoc-openapi will then inspect this method and the swagger annotations on this method level.

Note: beanClass and beanMethod are necessary to allow Springdoc inspect Service and resolve the API contracts.

@RouterOperations :

This annotation should be used if the Router bean contains multiple routes. When using RouterOperations, it’s mandatory to fill the path property.

@Operation: Annotation to document response status codes, Response Object,Request Body, Request Parameter etc.

Code Snippet - @RouterOperation Usage

5. Advanced Configuration

5.1. Grouping Api’s

Grouping API’s on basis of request mapping. Include the below property in the project’s properties to enable group API.

springdoc.api-docs.groups.enabled=true

Configure GroupedOpenAPI in Swagger config file as demonstrated in code snippet below, where two grouped API’s are created. All API’s having common path as “/swagger-demo/employee/” will be grouped under one group and those having “/swagger-demo/department/” will be under another one.

5.2. Documenting Common Headers

• OpenApiCustomiser: It is used to customise openAPI object.
• To include documentation for common headers you can write your own implementation of OpenApiCustomiseras below.
• Add each Header as Parameter Item in Operation. The header can be added as mandatory by adding “.required(true)” and assign default value to header by adding “.schema(new StringSchema().example(“test”))”.

Swagger Configuration

6. Swagger UI

Swagger UI will be exposed at http://localhost:8080/swagger-ui.html#/ by default.

NOTE: To change the default context path of swagger UI url, add below property in properties file and provide the required path.

springdoc.swagger-ui.path=/swagger-doc/swagger-ui.html
springdoc.api-docs.path=/swagger-doc/v3/api-docs

6.1. TEST

Now that we have everything set up, let’s take a look at our Swagger UI.

i) We have drop downs for both of the grouped API we have configured

GroupedOpenAPI for Employee and Department Service

ii)These are all the API’s we have exposed to Swagger for employee service

iii) This is how our request section looks.It contains information about Request Body Sample, Mandatory fields, Headers, required marks and their default value. We can try API with default values.

Header And Request Body Schema

Header And Request Body Example Value

IV) Response Codes for the API

All Response Code and Objects

7. Conclusion

Swagger is an exceptionally powerful tool. It provides absolute flexibility to automate the API documentation process.In this article we have demonstrated integrating our Weblux Application with functional programming model to Swagger for documentation using OpenAPI Specification.

8. References:

1. Github https://github.com/springdoc/springdoc-openapi/tree/master/springdoc-openapi-webflux-core
2. Spring WebFlux documentation: https://springdoc.org/