How to apply Springfox Swagger Global Parameters on Rest API CRUD

{getToc} $title={Table of Contents}

1. Introduction

In this tutorial, we'll look at Swagger 2 for a Spring REST web service, using the Springfox or springfox repo on github implementation of the Swagger 2 specification. If you are not familiar with Swagger, visit its web page to learn more.

I'm goint to apply it on my previouse existed Rest APIs CRUD with JDBI project. And I'm about to add a custom header in all APIs and use default response messages globally without writing in each API method too.

Documentation is a very important part of any restful API, Swagger had made it easy for developers to get a neat documentation for their API endpoints that is readable for both humans and machines only with a few steps. Swagger lists all API endpoints with detailed information about them like description, parameters and output schema in JSON format while Swagger-UI provides a styled interface with the ability to test the endpoints.

2. Dependency

Add the springfox dependency. The latest version can be downloaded from Maven Central.

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-boot-starter</artifactId>
	<version>3.0.0</version>
</dependency>

3. Configuration

Swagger Configuration with Global Request Parameter and Responses

Swagger configuration is done using Docket Bean, below is a simple configuration to integrate Swagger with Spring Boot, you can add more customization to your documentation in the Docket Bean, also you may create more than one Docket Bean.

package com.yuthads.springdatajdbi3crud.configuration;

import static com.google.common.collect.Lists.newArrayList;
import java.lang.reflect.Field;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.stream.Collectors;

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.builders.ResponseBuilder;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.ParameterType;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider;
import springfox.documentation.swagger.web.OperationsSorter;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger.web.UiConfigurationBuilder;

@Configuration
public class SwaggerConfig {

	private ApiInfo apiInfo() {
		return new ApiInfo("SpringFox Demo APIs",
        	"Demo APIs with spring boot rest api by usgin jdbi3","1.0","Terms of service",
        	new Contact("YUTHADS","https://yuthads.blogspot.com","yuthads@mail.com"),
        	"License of API", "API license URL",Collections.emptyList());
	}

	@Bean
	Docket api() {
    	return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
        	.securityContexts(Arrays.asList(securityContext()))
        	.securitySchemes(Arrays.asList(apiKey())).select()
        	.apis(RequestHandlerSelectors
            	.basePackage("com.yuthads.springdatajdbi3crud.controller"))
        	.paths(PathSelectors.ant("/api/product/**"))
            	.build().useDefaultResponseMessages(false)
        	.globalResponses(HttpMethod.GET,newArrayList(new ResponseBuilder()
        	.code("500").description("500 message").build(),new ResponseBuilder()
            	.code("403").description("Forbidden!!!!!").build()))
        	.globalRequestParameters(Arrays.asList(new RequestParameterBuilder().
        	name("x-global-header-1").description("Remote User")
            	.in(ParameterType.HEADER).required(true)
            	.query(simpleParameterSpecificationBuilder 
                	-> simpleParameterSpecificationBuilder
            	.allowEmptyValue(false).model(modelSpecificationBuilder 
                	-> modelSpecificationBuilder
            	.scalarModel(ScalarType.STRING))).build(),
            	new RequestParameterBuilder().name("x-global-header-2")
            	.description("Impersonate User").in(ParameterType.HEADER).required(false)
            	.query(simpleParameterSpecificationBuilder 
                	-> simpleParameterSpecificationBuilder
                .allowEmptyValue(false).model(modelSpecificationBuilder 
                	-> modelSpecificationBuilder
                .scalarModel(ScalarType.STRING))).build()));
	}

	@Bean
	UiConfiguration uiConfig() {
    		return UiConfigurationBuilder.builder()
        	.operationsSorter(OperationsSorter.METHOD).build();
	}
    
	private ApiKey apiKey() {
    		return new ApiKey("apiKey", "Authorization", "header");
	}

	private SecurityContext securityContext() {
    		return SecurityContext.builder().
            	securityReferences(defaultAuth()).build();
	}

	private List<SecurityReference> defaultAuth() {
    		return Arrays.asList(new SecurityReference("apiKey", 
            	new AuthorizationScope[0]));
	}

	@Bean
	static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
		return new BeanPostProcessor() {
			@Override
        		public Object postProcessAfterInitialization(Object bean, 
                	String beanName) throws BeansException {
        		if (bean instanceof WebMvcRequestHandlerProvider) {
            			customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
            		}
            		return bean;
        	}
        
        private <T extends RequestMappingInfoHandlerMapping> 
        	void customizeSpringfoxHandlerMappings(List<T> mappings) {
        	List<T> copy = mappings.stream()
        		.filter(mapping -> mapping.getPatternParser() == null)
        		.collect(Collectors.toList());
        		mappings.clear();
        		mappings.addAll(copy);
        	}
        
        @SuppressWarnings("unchecked")
        private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
        	try {
            	Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
                field.setAccessible(true);
                return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
            } catch (IllegalArgumentException | IllegalAccessException e) {
            	throw new IllegalStateException(e);
            }
        }
   };
  }
}

This library extensively uses googles guava library. For e.g. when you see newArrayList(…) its actually the guava equivalent of creating an normal array list and adding item(s) to it.

4. Explanation

The Docket bean of our application can be configured to give us more control over the API documentation generation process.

globalRequestParameters method in the Docket builder accepts a list of parameters that will be part of every API operation in the generated Swagger specification.

Parameters can be instantiated using RequestParameterBuilder , another builder class, which has methods to accept name, description,type of Parameter , is Required.

If any specifications need to be added to the parameter, use SimpleParameterSpecificationBuilder.

It is not always desirable to expose the documentation for the entire API. We can restrict Swagger’s response by passing parameters to the apis() and paths() methods of the Docket class.

As seen above, RequestHandlerSelectors filter the API according to the base package , class annotation, and method annotations. But can also allows using the any or none predicates.

PathSelectors provides additional filtering with predicates, which scan the request paths of our application. We can use any(), none(), regex(), or ant().

In the example below, we will instruct Swagger to include only controllers from a particular package, with specific paths, using the ant() predicate:

We don't need to add @EnableSwagger2 or @EnableSwagger2WebMvc since we are using springfox swagger with spring boot.

After defining the Docket bean, its select() method returns an instance of ApiSelectorBuilder, which provides a way to control the endpoints exposed by Swagger.

We can configure predicates for selecting RequestHandlers with the help of RequestHandlerSelectors and PathSelectors. Using any() for both will make documentation for our entire API available through Swagger.

In application.properties file add this property:

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER to flip that property back to its previous default value. But this won't help if you use actuators which are not effected by that property.

Within Swagger’s response is a list of all controllers defined in our application. Clicking on any of them will list the valid HTTP methods (DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT).

Expanding each method provides additional useful data, such as response status, content-type, and a list of parameters. It is also possible to try each method using the UI.

Note: We've used the @EnableSwagger2WebMvc annotation to enable Swagger, as it has replaced the @EnableSwagger2 annotation in version 3 of the libraries.

Swagger also provides some default values in its response, which we can customize, such as “Api Documentation”, “Created by Contact Email”, and “Apache 2.0”.

To change these values, we can use the apiInfo(ApiInfo apiInfo) method — the ApiInfo class that contains custom information about the API:

  private ApiInfo apiInfo() {
	return new ApiInfo("SpringFox Demo APIs", 
    	"Demo APIs with spring boot rest api by usgin jdbi3", "1.0","Terms of service", 
        new Contact("YUTHADS", "https://yuthads.blogspot.com", "yuthads@mail.com"),
        "License of API", "API license URL", Collections.emptyList());
}

Swagger allows globally overriding response messages of HTTP methods through Docket’s globalResponses() method.

First, we need to instruct Swagger not to use default response messages. Suppose we want to override 500 and 403 response messages for all GET methods.

To achieve this, some code must be added to the Docket’s initialization block (original code is excluded for clarity):

.useDefaultResponseMessages(false)
.globalResponses(HttpMethod.GET,
	newArrayList(new ResponseBuilder().code("500").description("500 message").build(),
	new ResponseBuilder().code("403").description("Forbidden!!!!!").build()));

And most of the user tries to find HTML swagger document file using {host}/swagger-ui.html or {host}/swagger-ui those are now removed.

Use This: {host}/swagger-ui/ to see the HTML document.

5. Demo & Testing

Let's start the application to generate the api document for the Spring Data REST APIs:

In my case, http://localhost:8080/swagger-ui/

swagger-ui

Request API:

request api via swagger-ui

API Responded:

api responsed via swagger-ui

6. Conclusion

Hope this article was helpful.

GitHub:

https://github.com/Yuth-Set/REST-CRUD-API-Spring-Data-JDBI-3.git

7. Ref.

https://springfox.github.io/springfox/docs/current/

https://github.com/springfox/springfox

How to apply Springfox Swagger Global Parameters on Rest API CRUD

1. Introduction

2. Dependency

3. Configuration

4. Explanation

5. Demo & Testing

Let's start the application to generate the api document for the Spring Data REST APIs:

Request API:

API Responded:

6. Conclusion

7. Ref.

Reactor RabbitMQ in your Reactive Spring Boot Application — Part 1

Reactor RabbitMQ in your Reactive Spring Boot Application — Part 2

What is Kubernetes and Containers and how does it work?

Spring Boot Project: Security with JJWT Authentication Token

How to apply Springfox Swagger Global Parameters on Rest API CRUD

1. Introduction

2. Dependency

3. Configuration

4. Explanation

5. Demo & Testing

Let's start the application to generate the api document for the Spring Data REST APIs:

Request API:

API Responded:

6. Conclusion

7. Ref.

You might like