Spring Boot优雅整合Swagger2，自动生成在线文档

Spring Boot优雅整合Swagger2，自动生成在线文档

日常求赞，感谢老板。

欢迎关注公众号：其实是白羊。干货持续更新中…

一、前言

现在的很多项目都是前后端分离的，后端提供接口，前端调用接口，在这个过程中一般后端会向前端提供一份接口文档，但是随着程序的调整，我们还要不断的去迭代接口文档，最后可能会搞出一堆，写起来比较耗时且在规范性上也很难要求。在这个前提下我们可以选择Swagger加入到我们的项目中。

Swagger提供了很多的功能，其中Swagger UI和Swagger Inspector使用的比较多

• Swagger UI：提供了一个UI页面描述项目中的接口（包括接口含义、uri、方法、参数、返回值和字段含义等）
• Swagger Inspector：提供了在线对接口进行测试的功能

二、集成Swagger

我们这里的项目框架是Spring Boot

1.引入依赖

<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.配置类

/**
 * @Description swagger配置文件
 * @Author ZhangLinlu
 * @Date 2020/10/10
 **/
@EnableSwagger2
@Configuration
public class SwaggerConfig {

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 设置页面标题
                .title("使用swagger2构建后端api接口文档")
                // 设置联系人
                .contact(new Contact("myname", "url", "email"))
                // 描述
                .description("欢迎访问后端接口文档，这里是描述信息")
                // 定义版本号
                .version("1.0").build();
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
            	//接口所在的包
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
                .paths(PathSelectors.any()).build();
    }
}

至此，我们就可以访问http://localhost:8080/swagger-ui.html看到swagger为我们提供的在线调试和在线接口文档的页面了

但是，目前上面的描述信息还不够详细。我们可以通过下面的注解来完善对接口、参数、返回值等的描述

3.常用注解

注解	标注位置和含义	属性以及取值含义
@Api	标注在接口类上，表示对此类接口的描述	tags=“说明此类下接口的含义”
@ApiOperation	标注在接口方法上，描述接口的用途	value=“说明方法的用途、作用” notes=“方法的备注”
@ApiImplicitParams	标注在请求的方法上，代表一组参数（运用于单体参数，不是javabean参数）	value = {@ApiImplicitParam…}
@ApiImplicitParam	写在@ApiImplicitParams的value={}中，描述每个参数	见附3.1
@ApiModel	标注在javabean参数和响应对象上，描述javabean含义	value=“描述对象含义”
@ApiModelProperty	标注在javabean参数和响应对象属性上，描述属性含义	name=“参数”,value=“含义”,required=true/false

附3.1：

• name=“参数”
• value=“参数含义描述”
• required=true/false是否必传
• paramType=“参数位置”
  • header：参数在请求头，通过@RequestHeader获取
  • query：参数通过@RequestParam获取
  • path：参数在restfull接口url上，通过@PathVariable获取
• dataType=“参数类型，如String等”
• defaultValue=“参数默认值”

举个栗子：

/**
 * @Description 测试接口
 * @Author ZhangLinlu
 * @Date 2020/10/10
 **/
@Api(tags = "测试接口")
@RestController
public class TestController {

    @ApiOperation(value = "我是test1接口",notes = "notes：我是test1")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "name",value = "姓名",required = true,paramType = "query",dataType = "String",defaultValue = "zll")
    })
    @GetMapping("test1")
    public Object test1(String name) {
        return "success" + name;
    }

    @ApiOperation(value = "我是test2接口",notes = "notes：我是test2")
    @GetMapping("test2")
    public Object test2(TestParamDTO testParamDTO) {
        return "success" + testParamDTO.getName();
    }
}

/**
 * @Description 测试javabean参数
 * @Author ZhangLinlu
 * @Date 2020/10/10
 **/
@Data
@ApiModel(value = "测试javabean参数")
public class TestParamDTO {

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

到这里已经完成了整个的整合，前端再让你出接口文档，直接url地址扔给她，潇洒转身离开。程序改动也不用重新写一份，改了哪里注解改一下就行了。

4.“你这页面好丑啊”

“你这页面好丑啊，接口多了也不好找。。。。”

“线上调试，接口做了鉴权没token怎么办。。。。”

面对这些吐槽，下面介绍一个好看的ui：knife4j（https://gitee.com/xiaoym/knife4j），这是个人维护的ui项目很好的解决了上面的问题

引入knife4j只需要引入相应的依赖，其他的都不用修改，完美兼容

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.2</version>
</dependency>

可以把之前引入的swagger依赖都去掉了，这个依赖包含了所需的swagger依赖

这次访问线上接口文档的地址改成了：http://localhost:8080/doc.html

不仅优化了ui界面，而且在文档管理中为我们提供了全局参数、离线文档等功能，很值得推荐。

三、最后

文章中的demo我已经上传到了gitee，需要的可以clone看一下：https://gitee.com/zhanglinlu/swagger-demo

点个赞啊亲

如果你认为本文对你有帮助，可以「在看/转发/赞/star」，多谢

如果你还发现了更好或不同的想法，还可以在留言区一起探讨下

---

欢迎关注公众号：「其实是白羊」干货持续更新中…