乐趣区

关于springboot:Spring-Boot优雅整合Swagger2自动生成在线文档

jiezi

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/…

点个赞啊亲

如果你认为本文对你有帮忙，能够「在看 / 转发 / 赞 /star」，多谢

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

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

退出移动版