Swagger 3 的基本使用

本内容根据江南一点雨松哥的 SpringBoot 付费视频所做的学习笔记，想具体详细了解内容的，请关注微信公众号：江南一点雨。

14.1 Swagger3 准备工作

swagger2和swagger3的区别

在 SpringBoot 中使用 Swagger3 需要导入以下依赖：

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

我们导入依赖后，此时创建一个 HelloController 接口，Swagger3 会自动帮助我们生成接口文档，不需要在进行任何配置。

文档接口地址：http://localhost:8080/v3/api-docs
文档页面地址：http://localhost:8080/swagger-ui/index.html

我们访问文档页面地址可以看到项目的接口文档。

我们可以通过配置类修改接口文档UI的内容：

@Configuration
public class swaggerConfig {@BeanDocket docket(){// 设置 swagger的版本return new Docket(DocumentationType.OAS_30)// 选择生成接口文档.select()// 包所在的路径.apis(RequestHandlerSelectors.basePackage("org.crc.swagger3.controller"))// 当前包下所有接口都生成.paths(PathSelectors.any()).build()// 接口文档初始化，也就是设置接口文档的详细信息，.apiInfo(new ApiInfoBuilder().description("xxx 项目接口文档")// 联系人.contact(new Contact("crc","https://blog.csdn.net/cenrc?spm=1001.2101.3001.5343","2516313840@qq.com")).version("v1.0").title("API 测试文档").license("Apache 2.0").licenseUrl("http://www.apache.org/licenses/LICENSE-2.0").build());}
}

修改之后接口文档的页面：

14.2 Swagger 3 的基本使用

注意，这里出现的注解有部分是 swagger 2中的注解，但是在swagger 3 中同样适用。

@ApiOperation注解。

在接口中添加 @ApiOperation ，用于表述接口的作用

@ApiOperation(value = "查询用户",notes = "根据 id 查询用户")
@GetMapping("/user/{id}")
public String getUserById(@PathVariable Integer id){return "user: " + id;
}

默认情况显示：

添加注解之后显示：

@ApiOperation注解是 swagger 2 中提供的注解，swagger 3同样提供了一个类似的注解 @Operation，可以实现与 @ApiOperation注解一样的效果。

使用方式：

// swagger 2
@ApiOperation(value = "查询用户",notes = "根据 id 查询用户")
// swagger 3
@Operation(summary = "查询用户",description = "根据 id 查询用户")

@ApiImplicitParam 注解。

基本使用方式：

@ApiImplicitParam(paramType = "path",name = "id",value = "用户 id",required = true)
@GetMapping("/user/{id}")
public String getUserById(@PathVariable Integer id){return "user: " + id;
}

@ApiImplicitParam 注解是用于描述接口的参数信息。

其中 paramType 属性表示参数的类型，参数的类型有以下几种：

path : 表示参数放在地址栏中

query ：表示参数是以 key / value 的形式传递

body ：表示参数是放在请求体中

name 属性表示参数的名字，value 属性表示参数的表述信息，required 属性表示参数是否是必须的（注意，这里相对的是swagger 接口文档而言，与项目实际运行无关）。

如果存在多个参数需要进行描述信息，那么可以使用@ApiImplicitParams注解。

@ApiImplicitParams({@ApiImplicitParam(paramType = "path",name = "id",value = "用户 id",required = true),@ApiImplicitParam(paramType = "body",name = "id",value = "用户 id",required = true)
})

默认情况显示：

添加注解之后显示：

@ApiResponses 注解。

通过使用 @ApiResponses 注解，我们可以设置接口返回状态码的提示信息。

@ApiResponses({@ApiResponse(responseCode = "200",description = "请求成功"),@ApiResponse(responseCode = "500",description = "请求失败")
})
@GetMapping("/user/{id}")
public String getUserById(@PathVariable Integer id){return "user: " + id;
}

默认情况显示：

添加注解之后显示：

与实体类相关的注解。

@ApiModel 注解与 @ApiModelProperty 的结合使用。

我们通过以上两个注解用户描述实体类的相关信息。

@ApiModel(value = "用户实体类",description = "这个类定义了用户的所有属性")
public class User {@ApiModelProperty(value = "用户 id")private int id;@ApiModelProperty("用户名")private String name;@ApiModelProperty("用户地址")private String address;
}@PostMapping("/user")
public User user(@RequestBody User user){return user;
}

默认情况显示：

添加注解之后显示：