Spring Boot-Swagger

一、什么是Swagger？

Swagger 是一个用于描述、构建和调用 RESTful API 的开源工具集。它提供了一种标准的、可视化的方式来定义 API 的结构、参数、请求和响应等信息。通过 Swagger，开发者可以方便地

Swagger 官方

Swagger 官网为 https://swagger.io/

主要掌握在 Spring Boot 中如何导入 Swagger 工具来展现项目中的接口文档

二、Swagger 的相关配置

2.1 导入maven依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

2.2 Swagger的相关配置

添加@Configuration 注解和@EnableOpenApi 注解

@EnableOpenApi
@Configuration
public class Swagger3Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30) // 使用 Swagger3.0 版本
.enable(true)// 是否关闭在线文档，生产环境关闭
apiInfo(apiInfo()) // 指定构建 api 文档的详细信息的方法
.select() // 指定要生成 api 接口的包路径 .apis(RequestHandlerSelectors.basePackage("com.jia.action"))
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 在方法接口上添加了 ApiOperation 注解
.paths(PathSelectors.any()).build().globalResponses(HttpMethod.GET, getGlobalResponseMessage())
.globalResponses(HttpMethod.POST, getGlobalResponseMessage());
}
// 生成摘要信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("接口文档") 设置页面标题
.description("说明信息") 设置接口描述
.contact(new Contact("bajie", "http://baidu.com", "jia@qq.com")) 设置联系方式
.version("1.0") 设置版本
.build(); 构建
}

此时，在浏览器中输入 http://localhost:8080/test/swagger-ui/，即可看到 swagger 的 接口页面，说明 Swagger 集成成功。

三、Swagger的使用

此时已经配置好了 Swagger，可以开始正常使用 Swagger， Swagger 中常用的注解，分别在实体类上、Controller 类上以及 Controller 中的方法上，

3.1 实体类注解

@ApiModel(value = "用户实体类")
public class User {

@ApiModelProperty(value = "用户唯一标识")
private Long id;
@ApiModelProperty(value = "用户姓名")
private String username;
@ApiModelProperty(value = "用户密码")
private String password;
}

3.2 Controller 类中相关注解

@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController {
@GetMapping("/get/{id}")
@ApiOperation(value = "根据用户唯一标识获取用户信息")
public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
// 模拟数据库中根据 id 获取 User 信息
User user = new User(id, "bajie", "123456");
return new JsonResult(user);
}
}

Swagger相关注解的说明：

1、@Api 注解用于类上，表示标识这个类是 swagger 的资源。

2、@ApiOperation 注解用于方法，表示一个 http 请求的操作。

3、@ApiParam 注解用于参数上，用来标明参数信息。

最后查看 Swagger 如何在页面 上呈现在线接口文档的，并且结合 Controller 中的方法在接口中测试一下数据。