Swagger 描述在 Spring Boot 应用程序中隐藏端点答案

【问题标题】：Swagger description hides endpoints in spring boot applicationSwagger 描述在 Spring Boot 应用程序中隐藏端点
【发布时间】：2021-10-11 10:06:03
【问题描述】：

我在我的应用程序中遇到了一个非常奇怪的行为。

@RestController
@RequestMapping("users")
@Validated
@Api(tags = "User controller v2")
public class UserController {

    @ApiOperation(value = "Get details of a user by id")
    @ApiResponses(value = {@ApiResponse(code = 400, message = "Bad Request"),
        @ApiResponse(code = 401, message = "Authorization information is missing or invalid."),
        @ApiResponse(code = 403, message = "Requested resource is forbidden for current user"),
        @ApiResponse(code = 200, message = "OK")})
    @GetMapping("/{userId}")
    public ResponseEntity<User> getUserDetails(@PathVariable @NotNull String userId) {
        // calling service methods
    }
}

这很好用，这就是我在 /swagger-ui.html 上看到的方式

但是，如果我在请求参数中添加任何 swagger 描述（如默认值），我将无法再在 swagger 中看到此方法：

@ApiOperation(value = "Get details of a user by id")
@ApiResponses(value = {@ApiResponse(code = 400, message = "Bad Request"),
    @ApiResponse(code = 401, message = "Authorization information is missing or invalid."),
    @ApiResponse(code = 403, message = "Requested resource is forbidden for current user"),
    @ApiResponse(code = 200, message = "OK")})
@GetMapping("/{userId}")
public ResponseEntity<User> getUserDetails(
    @ApiParam(defaultValue = "12345") @PathVariable @NotNull String userId) {
    // calling service methods
}

这就是我的招摇配置

public class WebConfiguration {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .securitySchemes(Collections.singletonList(apiKey()))
            .securityContexts(Collections.singletonList(securityContext()))
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.test"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("My test service")
            .version("2.0")
            .build();
    }

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

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

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[] {authorizationScope};
        return Collections.singletonList(new SecurityReference("JWT", authorizationScopes));
    }
}

另外，在我的应用日志中，我看到了这样的消息：

ERROR [,,,] 36927 --- [  restartedMain] s.d.s.web.scanners.ApiDescriptionReader  : Skipping process path[/api/v2/users/{userId}], method[getUserDetails] as it has an error.

任何想法为什么会发生以及如何解决它？

【问题讨论】：

标签： java spring spring-boot swagger

【解决方案1】：

在调试 Spring 上下文时，我在 ApiDescriptionReader 类中发现了这样的错误：

java.lang.NoSuchMethodError: io.swagger.annotations.ApiParam.allowEmptyValue()Z

我已经通过添加这个依赖解决了这个问题：

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.6.2</version>
</dependency>

【讨论】：