Maven 项目集成 Swagger2


题图:来自飞哥的图片工厂

音乐推荐:背叛
文丨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);
}
}

基本的用法就这些,好了,今天的分享就到这里了。

最后,我这边有个技术交流群,平常我会分享一些学习资源到群里,还可以和大家一起交流学习,需要的朋友可以扫描下面的二维码加我微信并备注「加群」,拉你进入技术交流群!

飞哥带你去装逼,一直装逼到天黑!

本文标题:Maven 项目集成 Swagger2

文章作者:x-sir

发布时间:2019年07月13日 - 16:12

最后更新:2019年07月13日 - 16:14

原始链接:http://www.x-sir.com/2019/07/13/Maven 项目集成 Swagger2/

许可协议: 署名-非商业性使用-禁止演绎 4.0 国际 转载请保留原文链接及作者。

-------------本文结束感谢您的阅读-------------
坚持原创技术分享,您的支持将鼓励我继续创作!
0%