简介

  • Open API是一个标准，它的主要作用是描述REST API，但是除了可以作为文档给开发者阅读，还可以让机器根据这个文档自动生成客户端代码等。 也可以自动生成Api文档

  • swagger是一种实现openApi规范的工具，我们常说的swagger一般指的是springfox-swagger，它是tswagger的再次具体实现与包装

    • 总之无论是springdoc还是fox-swagger他们都是openApi的实现

      使用springdoc

  • springdoc是一个类似swagger的接口管理文档工具，比fox-swagger更轻量，对新spring版本更兼容，侵入性更低。且也集成swagger。貌似对于已经采用springfox-swagger的项目也能识别

  • 自动识别时，没有使用@Operation注解标注的非Rest方法不会被识别到（即部不返回String的方法）

    引入依赖

  • 更旧的openapi版本可能会无法启动项目，测试时的**spring-boot-starter-parent**为**2.6.3**，搭配**1.4openapi**无法启动，搭配1.6.3启动成功

    1. <dependency>
    2.           <groupId>org.springdoc</groupId>
    3.           <artifactId>springdoc-openapi-ui</artifactId>
    4.           <version>1.6.3</version>
    5.       </dependency>

    配置

  • 配置与springdoc更多功能，见：SpringDoc · 语雀.pdf

    使用springdoc

  • 注解参数都是可选的

  • 貌似方法注解和控制器注解只能用于控制器里面才起作用
  • 控制器@Tag(name = "控制器大致说明", description = "控制器具体描述")
  • 接口方法@Operation(summary = "方法大致说明", description = "方法具体描述")

  • @Parameter(name = "参数名称", description = "参数描述", required = true) 最后一个是是否必须 用于参数列表中或者方法上

    • 使用在方法上时需要@Parameters({@Parameter(),...})

      访问接口管理页面

  • 默认的路径是：[http://?/swagger-ui.html]( )

    与springfox-swagger的对照

  • fox-swagger迁移到springdoc，不同作用的注解对比如下：

  • 参数说明与接口方法的注解可以同时使用。 | SpringFox | SpringDoc | | —- | —- | | @Api 作于于控制器类上 | @Tag | | @ApiIgnore | @Parameter(hidden = true)or@Operation(hidden = true) or @Hidden | | @ApiImplicitParam | @Parameter | | @ApiImplicitParams | @Parameters | | @ApiModel 作用于实体类 | @Schema | | @ApiModelProperty | @Schema | | @ApiOperation(value = “foo”, notes = “bar”)作用于接口方法 | @Operation(summary = “foo”, description = “bar”) | | @ApiParam 作用于参数、方法和字段上，类似@ApiModelProperty | @Parameter | | @ApiResponse(code = 404, message = “foo”) | ApiResponse(responseCode = “404”, description = “foo”) |