从零搭建自己的SpringBoot后台框架(六)

一：什么是Swagger

Swagger是一款通过我们添加的注解来对方法进行说明，来自动生成项目的在线api接口文档的web服务。

二：添加Swagger2依赖

1
2
3
4
5
6
7
8
9
10
11
1<dependency>

2   <groupId>io.springfox</groupId>

3   <artifactId>springfox-swagger2</artifactId>

4   <version>2.4.0</version>

5</dependency>

6<dependency>

7   <groupId>io.springfox</groupId>

8   <artifactId>springfox-swagger-ui</artifactId>

9   <version>2.4.0</version>

10</dependency>

11

然后鼠标右键选择Maven→Reimport进行依赖下载

三：创建Swagger2配置文件

在文件夹configurer中创建SwaggerConfigurer

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
1package com.example.demo.core.configurer;

2

3import org.springframework.context.annotation.Bean;

4import org.springframework.context.annotation.Configuration;

5import springfox.documentation.builders.ApiInfoBuilder;

6import springfox.documentation.builders.PathSelectors;

7import springfox.documentation.builders.RequestHandlerSelectors;

8import springfox.documentation.service.ApiInfo;

9import springfox.documentation.service.Contact;

10import springfox.documentation.spi.DocumentationType;

11import springfox.documentation.spring.web.plugins.Docket;

12import springfox.documentation.swagger2.annotations.EnableSwagger2;

13

14/**

15 * @author phubing

16 * @Description:Swagger2 配置文件

17 * @time 2019/4/20 22:42

18 */

19@Configuration

20@EnableSwagger2

21public class SwaggerConfigurer {

22

23    @Bean

24    public Docket createRestApi() {

25        return new Docket(DocumentationType.SWAGGER_2)

26                .apiInfo(apiInfo())

27                .select()

28                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))

29                .paths(PathSelectors.any())

30                .build();

31    }

32

33    private ApiInfo apiInfo() {

34        return new ApiInfoBuilder()

35                .title("mySpringBoot 使用Swagger2构建RESTful APIs")

36                .description("更多Spring Boot相关文章请关注：https://juejin.im/user/59e7fb9451882578e1406a51/posts")

37                .termsOfServiceUrl("https://juejin.im/user/59e7fb9451882578e1406a51/posts")

38                .contact(new Contact("Mr_初晨", "https://gitee.com/beany/mySpringBoot", null))

39                .version("1.0")

40                .build();

41    }

42}

43

四：修改Controller，添加API注解

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
1package com.example.demo.controller;

2

3@RestController

4@RequestMapping("userInfo")

5@Api(tags = {"用户操作接口"}, description = "userInfoControler")

6public class UserInfoController {

7

8    @Resource

9    private UserInfoService userInfoService;

10

11    @PostMapping("/hello")

12    public String hello() {

13        return "hello SpringBoot";

14    }

15

16    @ApiOperation(value = "查询用户", notes = "根据用户ID查询用户")

17    @ApiImplicitParams({

18            @ApiImplicitParam(name = "id", value = "用户ID", required = true,

19                    dataType = "Integer", paramType = "query")

20    })

21    @PostMapping("/selectById")

22    public RetResult<UserInfo> selectById(@RequestParam Integer id) {

23        UserInfo userInfo = userInfoService.selectById(id);

24        return RetResponse.makeOKRsp(userInfo);

25    }

26

27    @PostMapping("/testException")

28    public RetResult<UserInfo> testException(Integer id) {

29        List a = null;

30        a.size();

31        UserInfo userInfo = userInfoService.selectById(id);

32        return RetResponse.makeOKRsp(userInfo);

33    }

34

35

36}

37

38

注意参数前需加上@RequestParam

以上注解大家可以查看参考swagger官方注解文档进行自定义添加

五：接口测试

浏览器输入localhost:8080/swagger-ui.html我们可以看到。。哎呀我曹，页面呢？？

六：解决问题

继承WebMvcConfigurationSupport之后，静态文件映射会出现问题，需要重新指定静态资源

在WebConfigurer 中添加如下代码

1
2
3
4
5
6
7
8
9
10
11
1@Override

2public void addResourceHandlers(ResourceHandlerRegistry registry) {

3    registry.addResourceHandler("swagger-ui.html")

4            .addResourceLocations("classpath:/META-INF/resources/");

5    registry.addResourceHandler("/webjars/**")

6            .addResourceLocations("classpath:/META-INF/resources/webjars/");

7    registry.addResourceHandler("/favicon.ico")

8            .addResourceLocations("classpath:/META-INF/resources/favicon.ico");

9    super.addResourceHandlers(registry);

10}

11

七：接口测试

浏览器输入localhost:8080/swagger-ui.html我们可以看到如下页面

打开POST /userInfo/selectById

请求结果

八：英语看着不爽，怎么办？

根据swagger官方使用手册 找到关于本地化和翻译的说明：

九：添加翻译文件

在resourece目录下创建\META-INF\resourece目录，创建swagger-ui.html

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
1<!DOCTYPE html>

2<html>

3<head>

4    <meta charset="UTF-8">

5    <title>Swagger UI</title>

6    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/>

7    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/>

8    <link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>

9    <link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>

10    <link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>

11    <link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/>

12    <link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/>

13    <script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>

14    <script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>

15    <script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>

16    <script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>

17    <script src='webjars/springfox-swagger-ui/lib/handlebars-2.0.0.js' type='text/javascript'></script>

18    <script src='webjars/springfox-swagger-ui/lib/underscore-min.js' type='text/javascript'></script>

19    <script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script>

20    <script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script>

21    <script src='webjars/springfox-swagger-ui/lib/highlight.7.3.pack.js' type='text/javascript'></script>

22    <script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>

23    <script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script>

24    <script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>

25

26    <script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script>

27    <!--国际化操作：选择中文版 -->

28    <script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>

29    <script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>

30</head>

31

32<body class="swagger-section">

33<div id='header'>

34    <div class="swagger-ui-wrap">

35        <a id="logo" href="http://swagger.io">swagger</a>

36

37        <form id='api_selector'>

38            <div class='input'>

39                <select id="select_baseUrl" name="select_baseUrl"/>

40            </div>

41            <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/>

42            </div>

43            <div class='input'><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>

44            <div class='input'><a id="explore" href="#" data-sw-translate>Explore</a></div>

45        </form>

46    </div>

47</div>

48

49<div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>

50<div id="swagger-ui-container" class="swagger-ui-wrap"></div>

51</body>

52</html>

53

重点为<!–国际化操作：选择中文版 –>下两个js文件

translator.js为翻译器    zh-cn.js为中文脚本语言

十：测试

浏览器输入localhost:8080/swagger-ui.html我们可以看到如下页面

十一：样式丑？更换ui

swagger-bootstrap-ui

swagger-ui-layer