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

huangapple go评论88阅读模式
英文:

How to hide endpoints from OpenAPI documentation with Springdoc

问题

Springdoc会自动生成所有处理程序方法的API文档,即使没有OpenAPI注解。

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

英文:

Springdoc automatically generates a API documentation for all handler methods. Even if there are no OpenAPI annotations.

How can I hide endpoints from the API documentation?

答案1

得分: 26

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

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

示例:

@Hidden // 隐藏所有端点
@RestController
@RequestMapping(path = "/test")
public class TestController {

    private String test = "Test";

    @Operation(summary = "获取测试字符串", description = "返回一个测试字符串", tags = { "test" })
    @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "成功") })
    @GetMapping(value = "", produces = MediaType.TEXT_PLAIN_VALUE)
    public @ResponseBody String getTest() {
        return test;
    }

    @Hidden // 隐藏此端点
    @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)

英文:

The @io.swagger.v3.oas.annotations.Hidden annotation can be used at the method or class level of a controller to hide one or all endpoints.

(See: https://springdoc.org/faq.html#how-can-i-hide-an-operation-or-a-controller-from-documentation)

Example:

@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;
    }

}

Edit:

Its also possible to generate the API documentation only for controllers of specific packages.

Add following to your application.properties file:

springdoc.packagesToScan=package1, package2

(See: https://springdoc.org/faq.html#how-can-i-explicitly-set-which-packages-to-scan)

答案2

得分: 2

以下是翻译好的内容:

也可以仅为特定路径生成 API 文档。

将以下内容添加到您的 application.yml 文件中:

springdoc:
   paths-to-match: /api/**, /v1
英文:

Its also possible to generate the API doc only for specific Path.

Add following to your application.yml file:

springdoc:
   paths-to-match: /api/**, /v1

答案3

得分: 1

如果您正在使用Swagger Api并且想要隐藏特定的端点则可以在该端点上使用 `@ApiOperation(value = "获取建筑", hidden=true)`...hidden 属性应为 true

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

    @ApiOperation(value = "获取建筑", hidden=true)
    @GetMapping(value = "/{reference}")
    public Account getBuildings(@PathVariable String reference) {
        ....
    }
}
英文:

If you are working with Swagger Api and you want to hide specific endpoint then use @ApiOperation(value = "Get Building",hidden=true) on that endpoint...hidden attribute should be 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) {
        ....
    }

huangapple
  • 本文由 发表于 2020年5月30日 20:12:50
  • 转载请务必保留本文链接:https://go.coder-hub.com/62102261.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定