利用 Swagger 构建 Api 文档，提升你的对接效率_swagger dev-api

前言

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。越来越多的公司在项目中使用Swagger作为文档构建工具，Swagger主要有一下优点：

• 代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性
• 跨语言性，支持 40 多种语言
• Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程
• 还可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试

如果你还在手写Api文档，你可以尝试使用swagger去构建你的文档。你是否已经对 Swagger 产生了浓厚的兴趣了呢？下面我们就将一步一步地在 Spring Boot 项目中集成和使用 Swagger，让我们从准备一个 Spring Boot 的 Web 项目开始吧。

springboot 结合 swagger

1、在pom.xml中配置依赖

<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>
1
2
3
4
5
6
7
8
9
10

2、配置swaggerconfig信息

我们要使用swagger就需要编写一个swagger的配置文件，主要用来用来初始化swagger。配置信息如下：

@EnableSwagger2
@Configuration
//@Profile({"dev","test"})
@ConditionalOnProperty(name = "swagger.enable",havingValue = "true")
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.curry.springbootswagger.controller"))
                // 选择API路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // swagger ui 的标题
                .title("Spring Boot中使用 Swagger2 构建 Restful APIs")
                // 描述
                .description("更多信息关注公众号 平头哥的技术博文")
                // 外链
                .termsOfServiceUrl("https://www.jianshu.com/u/008ce054774c")
                // 文档的版本信息
                .version("1.0")
                .build();
    }
}
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

配置类的几个注解说明：

@Configuration：将该类自动加载到springboot的上下文中

@EnableSwagger2：启用swagger文档此注解也可以加在引导类，如果没有该注解，swagger文档将不会生效。

@Profile、@ConditionalOnProperty两个注解用来做条件判断，在特定的条件下才加载swagger配置类。一般情况下，在生产环境中我们需要禁用swagger文档，因为swagger文档会带来一些安全问题，我们就利用上述两个条件装配注解来解决。下面来说说这两个注解怎么使用？

@Profile({"dev","test"})：只在开发、测试环境启用swagger文档。{"dev","test"}根据你在springboot中配置的多环境为准。

@ConditionalOnProperty(name = "swagger.enable",havingValue = "true")：只有在配置文件中添加了swagger.enable=true的配置环境才启用swagger文档。

3、编写实体类

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

    @ApiModelProperty(value = "业务主键", accessMode = ApiModelProperty.AccessMode.READ_ONLY)
    private int id;

    @ApiModelProperty(value = "名称", required = true)
    private String name;

    @ApiModelProperty(value = "手机号码", required = true)
    private String mobile;

    @ApiModelProperty(value = "电子邮箱", required = true)
    private String email;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

注解说明：

@ApiModel：用来对类进行描述。主要参数说明：

@ApiModelProperty：用来对属性进行描述，主要参数说明

4、编写controller类

@RestController
@Api(tags = "用户管理", value = "用户管理")
public class UserController {

    Logger logger = LoggerFactory.getLogger(UserController.class);

    @Autowired
    private UserService userService;

    @ApiOperation(value = "查询用户")
    @GetMapping(path = "/user")
    public ResultDTO findUser() {
        ResultDTO resultDTO = new ResultDTO();
        try {
            resultDTO.setSuccess(true);
            resultDTO.setModule(userService.findUser());
        } catch (Exception e) {
            logger.error(e.getMessage());
            resultDTO.setSuccess(false);
            resultDTO.setErrorCode("400");
            resultDTO.setErrorMsg(e.getMessage());
        }
        return resultDTO;
    }

    @ApiOperation(value = "新增用户")
    @PostMapping(path = "/user")
    public ResultDTO insertUser(@RequestBody User user) {
        ResultDTO resultDTO = new ResultDTO();
        try {
            userService.insertUser(user);
            resultDTO.setSuccess(true);
        } catch (Exception e) {
            resultDTO.setSuccess(false);
            resultDTO.setErrorCode("400");
            resultDTO.setErrorMsg(e.getMessage());
            logger.error(e.getMessage());
        }
        return resultDTO;
    }

    @PutMapping(path = "/user")
    @ApiOperation(value = "更新用户",notes = "更新用户信息")
    public ResultDTO updateUser(@RequestBody User user) {
        ResultDTO resultDTO = new ResultDTO();
        try {
            userService.updateUser(user);
            resultDTO.setSuccess(true);
        } catch (Exception e) {
            resultDTO.setSuccess(false);
            resultDTO.setErrorCode("400");
            resultDTO.setErrorMsg(e.getMessage());
            logger.error(e.getMessage());
        }
        return resultDTO;
    }

    @DeleteMapping(path = "/user/{id}")
    @ApiOperation(value = "删除用户", notes = "根据ID删除用户信息")
//    @ApiImplicitParams({
//            @ApiImplicitParam(value="用户id",name = "id",paramType="path")
//    })
    public ResultDTO deleteUser(@ApiParam(value = "用户id",name = "id") @PathVariable(value = "id") int id) {
        ResultDTO resultDTO = new ResultDTO();
        try {
            userService.deleteUser(id);
            resultDTO.setSuccess(true);
        } catch (Exception e) {
            resultDTO.setSuccess(false);
            resultDTO.setErrorCode("400");
            resultDTO.setErrorMsg(e.getMessage());
            logger.error(e.getMessage());
        }
        return resultDTO;
    }

    @DeleteMapping(path = "/user/ingorApi")
    @ApiIgnore(value = "我是别忽略的API接口，我将不会在Swagger上显示")
    public ResultDTO ignoreApi() {
        ResultDTO resultDTO = new ResultDTO();
        resultDTO.setSuccess(true);
        return resultDTO;
    }

}
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
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

要是用swagger来做接口文档，需要在开发接口的时候添加一些接口注释，这样才能生成完整的接口文档。注解说明：

@Api：作用于类上，用来说明类的作用，

@ApiOperation：作用在方法上用来对方法进行说明。主要参数：

@ApiImplicitParams和@ApiImplicitParam：用在方法上，对参数进行说明，@ApiImplicitParams包含多个@ApiImplicitParam,@ApiImplicitParam主要参数：

@ApiParam：作用于单个参数，对于对参数的描述，主要参数说明：

@ApiIgnore：用来忽略该接口，加了@ApiIgnore的接口将不会在swagger文档上显示。

5、启动项目

访问http://127.0.0.1:8080/swagger-ui.html，

如果你觉得这界面不美观，OK，今天平头哥给你介绍一款更符合国人审美的ui框架swagger-ui-layer。

结合swagger-ui-layer

要使用swagger-ui-layer只需要做一个改动，在pom.xml中做如下调整.

        <!--注释掉springfox-swagger-ui-->
<!--        <dependency>-->
<!--            <groupId>io.springfox</groupId>-->
<!--            <artifactId>springfox-swagger-ui</artifactId>-->
<!--            <version>2.9.2</version>-->
<!--        </dependency>-->
        <!--添加swagger-ui-layer-->
        <dependency>
            <groupId>com.github.caspar-chen</groupId>
            <artifactId>swagger-ui-layer</artifactId>
            <version>1.1.3</version>
        </dependency>
1
2
3
4
5
6
7
8
9
10
11
12

重新启动项目，swagger-ui-layer的访问路径发生了变化，访问http://127.0.0.1:8080/docs.html，你将看到

界面是不是变得更加美观了，具体的使用就不在这里陈述了，体验一把就知道了。

更多关于swagger-ui-layer,点击这里

如果需要在一个swagger中集成多个项目，请参考程序员DD的博客：Spring Cloud Zuul中使用Swagger汇总API接口文档

demo下载：demo

个人公众号