关于springboot: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/…

点个赞啊亲

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

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


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

评论

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

这个站点使用 Akismet 来减少垃圾评论。了解你的评论数据如何被处理