OpenAPI-Swagger3-介绍使用

Posted 2020-12-21 jinyuanya

OpenAPI

是一个规范的名称。

3.0版本的对RESTful API方面做得很好。

Swagger

是一个 API文档维护组织，后来成为了 Open API 标准的主要定义者。现在最新的版本为17年发布的 Swagger3（Open Api3）。

是一个Open API规范实现工具包，由于Swagger工具是由参与创建原始Swagger规范的团队开发的，因此通常仍将这些工具视为该规范的代名词。目前可以认为Swagger3就是Open API 3.0

SpringFox

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

SpringDoc

也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中。

也是用来在 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用

整合springdoc-openapi

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

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

就这么简单，文档就构建完成了，不需要做任何的其他配置。

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

三、将API分组分组展示

配置方法

@Configuration
public class OpenAPIConfig {

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


}

显示效果,通过下拉选择分组，查看组内API

四、使用 swagger3 注解代替 swagger2注解

如果你希望为文档加上更详细的中文注释，使用如下注解（对比Swagger2注解使用方法使用即可）。但是笔者觉得没有必要学习这东西，意义不大。注意变量、接口命名规范，英文的接口文档就挺好。

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

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

更多内容指引官网：https://springdoc.org/