Spring boot: swagger: document allowable values of a header

Using 'allowableValues' attribute of @ApiImplicitParam annotation, we can specify allowable values to the header.

 

Example

@ApiImplicitParams({
	@ApiImplicitParam(name = "Authorization", value = "please pass sso token in the format Beare XXASDACS", 
                                          dataType = "String", paramType = "header", required = true),
	@ApiImplicitParam(name = "processingType", value = "some random string", 
                                         dataType = "String", paramType = "header", required = false, allowableValues = "fullDetails, nameAndIdOnly,nameOnly")
})

 

In the above snippet, I documented the header ‘processingType’ with below possible values.

 

a.   fullDetails,

b.   nameAndIdOnly,

c.    nameOnly

 

we can document the possible values in three ways.

 

a.   To set a list of values, provide a comma-separated list.

For example: {@code first, second, third}

b.   To set a range of values, start the value with "range", and surrounding by square brackets include the minimum and maximum values, or round brackets for exclusive minimum and maximum values.

For example: {@code range[1, 5]}, {@code range(1, 5)}, {@code range[1, 5)}

c.    To set a minimum/maximum value, use the same format for range but use "infinity" or "-infinity" as the second value.

For example, range[1, infinity] means the minimum allowable value of this parameter is 1.

 

Find the below working application.

 

Step 1: Create new maven project ‘swagger-specify-allowable-value-of-header’.

 

Step 2: Update pom.xml with maven dependencies.

 

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.sample.app</groupId>
	<artifactId>swagger-specify-allowable-value-of-header</artifactId>
	<version>1</version>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.3.12.RELEASE</version>
	</parent>


	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>


		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>

	</dependencies>
</project>

 

Step 3: Define SwaggerConfig class.

 

SwaggerConfig.java

 

package com.sample.app.config;

import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Component
@EnableAutoConfiguration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket docketApi() {

		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().paths(PathSelectors.any()).build();
	}

	private ApiInfo apiInfo() {

		return new ApiInfoBuilder().title("Spring boot swagger demo application").description("REST APIs for spring boot service")
				.license("Apache License Version 2.0").licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
				.version("2.0").build();
	}
}

 

Step 4: Define UserController class.

 

UserController.java

package com.sample.app.controller;

import java.util.HashMap;
import java.util.Map;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.CrossOrigin;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping(value = "/api/v1/users")
@Api(tags = { "user" })
@CrossOrigin("*")
public class UserController {

	@ApiOperation(value = "Get information about me", notes = "This API will get information about me")
	@ApiImplicitParams({
			@ApiImplicitParam(name = "Authorization", value = "please pass sso token in the format Beare XXASDACS", dataType = "String", paramType = "header", required = true),
			@ApiImplicitParam(name = "processingType", value = "some random string", dataType = "String", paramType = "header", required = false, allowableValues = "fullDetails, nameAndIdOnly,nameOnly") })
	@GetMapping("/about-me")
	public ResponseEntity<Map<String, Object>> aboutMe() {
		Map<String, Object> myDetails = new HashMap<>();
		myDetails.put("id", 1);
		myDetails.put("name", "Krishna");

		return ResponseEntity.ok(myDetails);

	}

}

 

Step 5: Define main application class.

 

App.java

 

package com.sample.app;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class App {
	public static void main(String[] args) {

		SpringApplication.run(App.class, args);

	}
}

 

Total project structure looks like below.

 

Run App.java and open the url ‘http://localhost:8080/swagger-ui.html’ to experiment with swagger documentation.

 

You can download complete working application from this link.

Previous                                                    Next                                                    Home