Hide Spring boot parameters and endpoints in Swagger

How to hide parameters and endpoints from swagger

Chirag S P

2022-02-25

When we setup swagger documentation, a need might arise to hide endpoints or parameters. We might have a scenario wherein an endpoint is still being developed and we don’t want it being used by the end user, or some special parameters might be used like Pricipal or Http related parameters and this need not appear in Swagger documentation.

How to hide parameters in Swagger

First lets look into how to hide parameters in Swagger.

Consider for example below endpoint,

	@ApiOperation(value = "Update order using order id")
	@PutMapping(path="/order/update/id/{orderId}",
			produces= {MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE})
	@ResponseStatus(HttpStatus.CREATED)
	public Order updateOrder(
			@PathVariable(name = "orderId",required=true) String orderId,
			@RequestBody OrderUpdateRequest orderUpdateRequest,
			Principal principle) throws OrderUpdateException, InvalidArgumentExpection {
		if(orderId!=null && orderId!="" && orderUpdateRequest!=null) {
			try {
				int intOrderId = Integer.parseInt(orderId);
				return this.orderService.updateOrderByOrderId(intOrderId, orderUpdateRequest,principle.getName());
			}catch(NumberFormatException e) {
				throw new OrderUpdateException("Provided OrderId is not valid");
			}
		}else {
			throw new InvalidArgumentExpection("OrderId and orderUpdateRequest cannot be empty");
		}
	}

Here I want Principal principle parameter to be hidden in swagger.

In the Swagger config under api() method call ignoredParameterTypes and pass the class to be ignored by Swagger as the parameter to this.

For example,

@Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
        		.ignoredParameterTypes(Principal.class)
                .apiInfo(apiInfo())
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(apiKey()))
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build();
    }

Now wherever Pricipal class is passed as parameter in any Rest endpoint in the entire application, it will be ignored by swagger.

How to hide endpoints in Swagger

There are several ways in which one can hide API endpoints in Swagger.

1. Using @ApiIgnore

@ApiIgnore can be hide elements in swagger in multiple ways.

@ApiIgnore allows us to hide specific swagger endpoints. Example of the same is shown below,

@ApiIgnore
@ApiOperation(value = "This method is used to get the user details.")
@GetMapping("/getUser")
public String getUser() {
    return "Test User";
}

As well hiding specific swagger endpoints, @Apiignore can be used to hide all endpoints of a controller class. It can be implemented as shown below,
```
@ApiIgnore
@RestController
public class ExampleController {
    // example code
}
```

2. Using @ApiOperation

@ApiOperation is used to hide specific single endpoints from swagger.

@ApiOperation(value = "Returns user", hidden = true)
@GetMapping("/getDate")
public String getUser() {
    return "Test User";
}

3. Using @Hidden

Instead of @ApiIgnore and ApiOperation, we can simple use @Hidden annotation to hide an endpoint.

@Hidden
@GetMapping("/getUser")
public String getUser() {
    return "Test User";
}

As well as hiding specific endpoints, @Hidden can be used to hide entire controller class.

@Hidden
@RestController
public class ExampleController {
    // example code
}

So that is how we implement hiding Spring boot parameters or endpoints in Swagger.

If you want to checkout more articles related to Java go to https://chiragsp.dev/tags/java/