hooyantsing's Blog

青铜篇_P19_使用OpenAPI构建接口文档

字数统计: 310阅读时长: 1 min
2020/07/16

使用OpenAPI构建接口文档

20年全新-Spring Boot 2.x从青铜到王者之青铜篇-打造精品中的精品-程序员-编程-架构师-SpringBoot

什么是 OpenAPI 和 Swagger 有什么关系

OpenAPI是规范,Swagger3是OpenAPI3.0的实现。

SpringFox 和 SpringDoc 的区别

是两个不同的项目,SpringFox是将Swagger2集成到Spring当中。SpringDoc是将OpenAPI的实现,也就是Swagger3集成到Spring当中。

  • Swagger2,使用SpringFox
  • Swagger3,使用SpringDoc

    依赖

想要使用Swagger3,请先将Swagger2相关的东西清除掉。反之亦然。

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

引入依赖后,启动项目,访问:http://localhost:8888/swagger-ui.html

API 进行分组

和Swagger2一样,创建一个Config类。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
package xyz.hooy.demo.bronze.p19;

import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

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

效果:

6caab911ba867e150dc3e5efad6dca63.png

Swagger2 和 OpenAPI3 注解对应关系

|@ApiParam |@Parameter |
|@ApiOperation |@Operation |
|@Api |@Tag |
|@ApilmplicitParams|@Parameters |
|@ApilmplicitParam |@Parameter |
|@Apilgnore |@Parameter(hidden = true) or @Operation(hidden = true) or @Hidden|
|@ApiModel |@Schema |
|@ApiModelProperty |@Schema |

CATALOG
  1. 1. 使用OpenAPI构建接口文档
    1. 1.1. 什么是 OpenAPI 和 Swagger 有什么关系
    2. 1.2. SpringFox 和 SpringDoc 的区别
      1. 1.2.1. 依赖
      2. 1.2.2. API 进行分组
    3. 1.3. Swagger2 和 OpenAPI3 注解对应关系