如何使用 Springdoc 从 OpenAPI 文档中隐藏端点

Posted 2023-03-10

【中文标题】如何使用 Springdoc 从 OpenAPI 文档中隐藏端点

【英文标题】：How to hide endpoints from OpenAPI documentation with Springdoc

【发布时间】：2020-09-17 23:38:59

【问题描述】：

Springdoc 自动为所有处理程序方法生成 API 文档。即使没有 OpenAPI 注释。

如何从 API 文档中隐藏端点？

【参考方案1】：

@io.swagger.v3.oas.annotations.Hidden 注释可用于控制器的方法或类级别以隐藏一个或所有端点。

（参见：https://springdoc.org/faq.html#how-can-i-hide-an-operation-or-a-controller-from-documentation）

例子：

@Hidden // Hide all endpoints
@RestController
@RequestMapping(path = "/test")
public class TestController 

    private String test = "Test";

    @Operation(summary = "Get test string", description = "Returns a test string", tags =  "test" )
    @ApiResponses(value =  @ApiResponse(responseCode = "200", description = "Success" ) )
    @GetMapping(value = "", produces = MediaType.TEXT_PLAIN_VALUE)
    public @ResponseBody String getTest() 
        return test;
    

    @Hidden // Hide this endpoint
    @PutMapping(value = "", consumes = MediaType.TEXT_PLAIN_VALUE)
    @ResponseStatus(HttpStatus.OK)
    public void setTest(@RequestBody String test) 
        this.test = test;
    

编辑：

也可以只为特定包的控制器生成 API 文档。

将以下内容添加到您的 application.properties 文件中：

springdoc.packagesToScan=package1, package2

（参见：https://springdoc.org/faq.html#how-can-i-explicitly-set-which-packages-to-scan）

【讨论】：

或者你可以使用：SpringDocUtils.getConfig().addHiddenRestControllers(BasicErrorController.class);

【参考方案2】：

如果您正在使用 Swagger Api 并且想要隐藏特定端点，则在该端点上使用 @ApiOperation(value = "Get Building",hidden=true)...hidden 属性应该为 true。

@RestController
@Api(tags="Building")
@RequestMapping(value="/v2/buildings")
public class BuildingsController 

    @ApiOperation(value = "Get Building",hidden=true)
    @GetMapping(value = "/reference")
    public Account getBuildings(@PathVariable String reference) 
        ....