Spring Boot 集成 Swagger,生成接口文档就这么简单!

之前的文章介绍了《推荐一款接口 API 设计神器!》,今天栈长给大家介绍下如何与优秀的 Spring Boot 框架进行集成,简直不能太简单。

你所需具备的基础

更多请在Java技术栈微信公众号后台回复关键字:boot。

Spring Boot 集成 Swagger

1、添加依赖

Maven依赖示例:

1
2
3
4
5
6
7
8
9
<!-- Swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>

2、在 Spring Boot 配置文件中添加配置参数。

1
2
3
4
5
6
7
8
9
10
swagger:
title: API标题
description: API描述
version: 1.0
terms-of-service-url: http://www.javastack.cn/
base-package: cn.javastack.test.web
contact:
name: Javastack
url: http://www.javastack.cn/
email: admin@javastack.cn

3、添加配置类

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
@Getter
@Setter
@Configuration
@EnableSwagger2
@ConditionalOnClass(EnableSwagger2.class)
@ConfigurationProperties(prefix = "swagger")
public class SwaggerConfig {

/**
* API接口包路径
*/
private String basePackage;

/**
* API页面标题
*/
private String title;

/**
* API描述
*/
private String description;

/**
* 服务条款地址
*/
private String termsOfServiceUrl;

/**
* 版本号
*/
private String version;

/**
* 联系人
*/
private Contact contact;

@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(title)
.description(description)
.termsOfServiceUrl(termsOfServiceUrl)
.version(version)
.contact(contact)
.build();
}

}

如何使用

Swagger 默认会根据配置的包,扫描所有接口并生成对应的 API 描述和参数信息,但这样不是很直观,需要对每个接口和参数进行自定义描述。

常用的 Swagger 注解如下。

注解名称 使用说明
@Api 描述一个 API 类
@ApiImplicitParam 描述一个请求参数
@ApiImplicitParams 描述一组请求参数
@ApiModel 描述一个返回的对象
@ApiModelProperty 描述一个返回的对象参数
@ApiOperation 描述一个 API 方法
@ApiParam 描述一个方法的参数
@ApiResponse 描述一个请求响应
@ApiResponses 描述一组请求响应

使用示例如:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Api(description = "登录模块")
@RestController
public class LoginController {

@ApiOperation(value = "登录", httpMethod = "POST")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", dataType = "string", paramType = "query"),
@ApiImplicitParam(name = "password", value = "密码", dataType = "string", paramType = "query")})
@PostMapping(value = "/login")
public Object login(@RequestParam("username") String username, @RequestParam("password") String password) {

// ...

}
}

http://localhost:8080/swagger-ui.html

打开 swagger-ui 界面,可以看到所有的 API 接口定义,也可以在上面发起接口测试。

好了,今天的分享就到这里,更多 Spring Boot 文章正在撰写中,关注Java技术栈微信公众号获取第一时间推送。

在公众号后台回复:boot,还能获取栈长整理的往期 Spring Boot 教程,都是实战干货,以下仅为部分预览。

  • Spring Boot 读取配置的几种方式
  • Spring Boot 如何做参数校验?
  • Spring Boot 最核心的 25 个注解!
  • Spring Boot 2.x 启动全过程源码分析
  • Spring Boot 2.x 新特性总结及迁移指南
  • ……

本文原创首发于微信公众号:Java技术栈(id:javastack),转载请原样保留本信息。