题图：来自飞哥的图片工厂
音乐推荐：背叛
文丨IT大飞说
预计阅读时间：3.2 分钟
哈喽，朋友们，今天我们来学习下如何使用 Swagger2。
什么是 Swagger?
Swagger 是一款 RESTFUL 接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。
如何集成？
打开 pom.xml 文件，添加如下依赖：
1
2
3
4
5
6
7
8
9
10
| <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
|
注：编写本文时使用的最新版本是 2.9.2，当你看到这篇文章的时候可能会有更新，最新的版本可到 https://mvnrepository.com 查看。
新建一个 Swagger2 类，完整代码如下：
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
| @Configuration
@EnableSwagger2 // 启用 Swagger
@EnableWebMvc
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.xpf.imoney"))
.paths(PathSelectors.any())
.build();
}
/**
* 构建 api 文档的详细信息函数，注意这里的注解引用的是哪个
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 页面标题
.title("SSM Application [iMoney] Swagger2 RESTFul API")
// 创建人
.contact(new Contact("x-sir", "http://www.x-sir.com", "542270559@qq.com"))
// 版本号
.version("1.0")
// 描述
.description("This is [iMoney] API doc")
.build();
}
}
|
然后编译并启动你本地的服务，打开浏览器，输入下面的访问地址：
1
| http://localhost:8080/JavaWeb/swagger-ui.html
|
注：上面链接中的 JavaWeb 为你的项目名称，替换为你自己的！
正常情况下你就会看到下面的页面了：
Swagger 的几个常用注解
- @Api：表示这个类是 Swagger 的资源；
- @ApiOperation：用在方法上，说明方法的作用；
- @ApiParam：用来修饰参数，表示对参数添加元数据；
- @ApiModel：用于类，对类进行说明；
- @ApiIgnore：用于类，方法，表示这个类或方法被忽略；
- @ApiImplicitParam：用于方法，表示单独的请求参数；
举个例子，我们的 UserController 中的简单使用，完整代码如下：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| @Api(value = "/user", description = "关于用户的一些操做。")
@Controller
public class UserController {
@Resource
private UserService userService;
@ResponseBody
@RequestMapping(value = "/index")
@ApiOperation(value = "通过 ID 查询 USER 信息", httpMethod = "GET", notes = "暂无")
public User index(@RequestParam("id") int id) {
return userService.getUserById(id);
}
}
|
基本的用法就这些，好了，今天的分享就到这里了。
最后，我这边有个技术交流群，平常我会分享一些学习资源到群里，还可以和大家一起交流学习，需要的朋友可以扫描下面的二维码加我微信并备注「加群」，拉你进入技术交流群！
飞哥带你去装逼，一直装逼到天黑！