Spring Boot整合Swagger3(OpenAPI)

一、Swagger3介绍

1、Swagger

• 是一个 API文档维护组织，后来成为了 Open API 标准的主要定义者。现在最新的版本为17年发布的 Swagger3（Open Api3）。
• 是一个Open API规范实现工具包，由于Swagger工具是由参与创建原始Swagger规范的团队开发的，因此通常仍将这些工具视为该规范的代名词。目前可以认为Swagger3就是Open API 3.0

2、OpenAPI 3.0

2017年7月，Open API Initiative最终发布了OpenAPI Specification 3.0.0。它对2.0规范进行了很多改进。Open API 3.0规范可以用JSON或YAML编写，并且在记录RESTful API方面做得很好。同时标志着Swagger2成为过去式。 

3、SpringFox

SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。截至2020年4月，尚未支持 OpenAPI3 标准。

4、SpringDoc

SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中。
也是用来在 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。

二、Spring Boot整合整合springdoc-openapi

1、导入springdoc-openapi依赖

在pom.xml里面去掉springfox，添加如下的openapi依赖。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.4.0</version>
</dependency>

2、编写Swagger3的配置类

Swagger3对API分组展示

@Configuration
@OpenAPIDefinition(info =
@Info(title = "一点教程网-Swagger3.0构建API文档", version = "1.0", description = "一点教程网-Swagger3.0构建API文档 v1.0")
)
public class Swagger3Configuration {

    @Bean
    public GroupedOpenApi restApi() {
        return GroupedOpenApi.builder()
                .group("rest-api")
                .pathsToMatch("/rest/**")
                .build();
    }

    @Bean
    public GroupedOpenApi helloApi() {
        return GroupedOpenApi.builder()
                .group("hello")
                .pathsToMatch("/hello/**")
                .build();
    }
}

3、修改注解为Swagger3的主键

用 swagger 3 的注解（已经在上面maven包引入）代替 swagger 2 的注解，swagger 3 注解的包路径为io.swagger.v3.oas.annotations。

Controller接口的注解：

@Operation(summary = "添加文章", description = "添加新的文章", tags = "Article",method = "POST")
  @Parameters({
          @Parameter(name = "title", description = "文章标题", required = true),
          @Parameter(name = "content", description = "文章内容", required = true),
          @Parameter(name = "categoryName", description = "文章类别", required = true)
  })
  @PostMapping("/article")
  public @ResponseBody  ResponseResult saveArticle2(
          @RequestParam(value="title") String title,  //参数1
          @RequestParam(value="content") String content,//参数2
          @RequestParam(value="categoryName") String categoryName//参数3
  ) {
    log.info("添加文章");
    return ResponseResult.success();
  }

Model上注解：

@Data
@Schema(title = "通用响应数据结构类")
public class ResponseResult {
  @Schema(title="请求是否处理成功")
  private boolean isok;  //请求是否处理成功
  @Schema(title="请求响应状态码",example="200、400、500")
  private int code; //请求响应状态码（200、400、500）
  @Schema(title="请求结果描述信息")
  private String message;  //请求结果描述信息
  @Schema(title="请求结果数据")
  private Object data; //请求结果数据（通常用于查询操作）

4、重启测试

访问：http://localhost:8888/swagger-ui.html

三、Swagger3 和 Swagger2 注解区别

Swagger2注解	OpenAPI3(swagger3)注解
@ApiParam	@Parameter
@ApiOperation	@Operation
@Api	@Tag
@ApiImplicitParams	@Parameters
@ApiImplicitParam	@Parameter
@ApiIgnore	@Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiModel	@Schema
@ApiModelProperty	@Schema

 

下载本文源码：springboot-demo