Java 如何在 Spring Boot 的 Swagger 文档中隐藏端点

How to hide endpoints from Swagger documentation in Spring Boot

提问by Alberto

I have a Spring Boot project with next dependency of Swagger:

我有一个 Spring Boot 项目，下一个依赖 Swagger：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <scope>compile</scope>
</dependency>

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

And I have my Interface:

我有我的界面：

import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@RequestMapping(value = "/cache")
@ApiIgnore
@Api(hidden = true)
public interface CacheController {

    @RequestMapping(
        value = "clear/",
        method = RequestMethod.GET,
        produces = {MediaType.APPLICATION_JSON_VALUE, MediaType.TEXT_PLAIN_VALUE}
    )
    @ApiOperation(value = "", hidden = true)
    ResponseEntity<String> clearToken();
}

The annotations @ApiIgnoreand @Api(hidden = true)(I've tested them separately and they don't work either.) haven't effects to hide the documentation. It only works if the annotation is over the method, but I would like hide them all since I have other endpoints I'd like to hide.

注释@ApiIgnore和@Api(hidden = true)（我已经单独测试过它们，它们也不起作用。）没有隐藏文档的效果。它仅在注释在方法上时才有效，但我想将它们全部隐藏，因为我有其他想要隐藏的端点。

Some ideas?

一些想法？

EDIT:

编辑：

This is my Swagger configuration:

这是我的 Swagger 配置：

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.RequestMethod;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.ResponseMessage;
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.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    public static String API_KEY_NAME;

    @Bean
    public Docket apiDocumentation() {
        List<ResponseMessage> errorList = this.defineResponseMessages();

        return new Docket(DocumentationType.SWAGGER_2)  
          .select()       
          .apis(RequestHandlerSelectors.basePackage("my.package.rest"))              
          .paths(PathSelectors.any())                          
          .build()
          .useDefaultResponseMessages(true)
          .globalResponseMessage(RequestMethod.GET, errorList)
          .securitySchemes(Arrays.asList(this.apiKey()))
          .securityContexts(Arrays.asList(this.securityContext()))
          .apiInfo(this.apiInfo());                                          
    }

    @Value("${server.security.apiKeyName}")
    public void setApiKeyName(final String apiKeyName) {
        SwaggerConfig.API_KEY_NAME = apiKeyName;
    }

    private ApiKey apiKey() {
        return new ApiKey("apiKey", API_KEY_NAME, "header");
    }

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

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Arrays.asList(new SecurityReference("apiKey", authorizationScopes));
    }

    private List<ResponseMessage> defineResponseMessages() {
        List<ResponseMessage> errorList = new ArrayList<ResponseMessage>();

        ResponseMessage responseMessage = new ResponseMessageBuilder()
            .code(HttpStatus.INTERNAL_SERVER_ERROR.value())
            .message(HttpStatus.INTERNAL_SERVER_ERROR.getReasonPhrase())
            .build();

        errorList.add(responseMessage);

        responseMessage = new ResponseMessageBuilder()
                .code(HttpStatus.UNAUTHORIZED.value())
                .message(HttpStatus.UNAUTHORIZED.getReasonPhrase())
                .build();

        errorList.add(responseMessage);

        responseMessage = new ResponseMessageBuilder()
                .code(HttpStatus.NOT_FOUND.value())
                .message(HttpStatus.NOT_FOUND.getReasonPhrase())
                .build();

        errorList.add(responseMessage);

        return errorList;
    }

    private ApiInfo apiInfo() {
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        return apiInfoBuilder
            .title("My API")
            .description("Description")
            .version("1.0.0 Beta")
            .build();
    }
}

采纳答案by Matt Ke

You have added the @ApiIgnoreannotation on an interface. It looks like, this annotation doesn't work when added on an interface. (I really don't understand why @Apiworks on an interface and @ApiIgnoredon't. )

您已@ApiIgnore在接口上添加了注释。看起来，这个注释在添加到界面上时不起作用。（我真的不明白为什么@Api在界面上工作，而@ApiIgnore不是。）

Add the annotation directly to your controller class. This should solve your problem.

将注释直接添加到您的控制器类。这应该可以解决您的问题。

The hiddenproperty on the @Apiannotation doesn't work currently. (See thisGitHub issue.)

注释上的hidden属性@Api当前不起作用。（请参阅此GitHub 问题。）

回答by Purushotham CK

One more way is to use @ApiOperation(hidden = true)This can be used at controller/handler level method. E.g.

@ApiOperation(hidden = true)另一种方法是使用This 可以在控制器/处理程序级别方法中使用。例如

@RestController
public HomeController{
@ApiOperation(value = "<Your Message>", hidden = true)
    public String getMessage(@RequestParam(value = "msg") final String msg){
        return msg;
    }
}

回答by Good Lux

Another option is to just remove the @Api completely, and your controller and its methods shouldn't be picked up by swagger.

另一种选择是完全删除@Api，并且您的控制器及其方法不应该被招摇。

回答by user2122524

The scenario where we want to hide only a particular method(s) from the class. For swagger.v3 there is an annotation with name Hiddenin io.swagger.core.v3:swagger-annotations:2.0.10 jar. Methods to be hidden can be annotated with Hiddenannotation as shown below. The below method shows the method with DELETEoperation which needs to be hidden from the swagger documentation.

我们只想从类中隐藏特定方法的场景。对于 swagger.v3，有一个名为Hiddenin的注释io.swagger.core.v3:swagger-annotations:2.0.10 jar。要隐藏的方法可以使用注释进行Hidden注释，如下所示。下面的方法显示了DELETE需要从 swagger 文档中隐藏的操作方法。

@DELETE
@Hidden
public void deleteList(int id) {
//code goes here.
}

回答by u33how

For OpenAPI3and SpringBoot:
I used @Hidden annotation on a method of a controller.
It seems to work both at method level and controller level.

对于OpenAPI3和SpringBoot：
我在控制器的方法上使用了 @Hidden 注释。
它似乎在方法级别和控制器级别都有效。

@Hidden annotation was imported from using:

@Hidden 注释是从使用导入的：

import io.swagger.v3.oas.annotations;