Swagger还在用老版本的UI界面吗？最新的Knife4j送给你

本文链接：https://blog.youkuaiyun.com/junwen0814/article/details/116941613

概述

Swagger是什么

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，效果看下图

Swagger历史

springfox-swagger-ui

Swagger官方出厂的Swagger文档Ui界面对用户其实不是很友好，上下滑动，当接口过多的时候，接口直接有前后调用关系的时候，经常会找晕掉。
在这里插入图片描述

swagger-bootstrap-ui

之后国人开发出了swagger-bootstrap-ui,这个Ui界面用了我们国人比较适应的左右方式
在这里插入图片描述

Knife4j

但随着项目的发展,仅仅一个皮肤已经不能满足开发者的需求，需要增加更多的服务端代码来满足开发者的需求，所有出现了最新的Knife4j
在这里插入图片描述

这类UI界面都比较好看，关键有一点我比较喜欢的是他有搜索框，我可以搜索某个接口，不然之前官方那种上下滑，层级还多的，我想找一个接口要找很久，实在难受

Swagger能做什么

对于我们后端来说

测试的时候不用再手写那么多参数了，直接按照Swaager生成的接口参数填入测试即可

给每个接口上增加注解的方式定义文档接口，降低代码侵入性
变更接口的时候，可以随时更新，不需要手动去维护
程序如果出问题了，只需要先检测Swagger的接口是否正常即可

对于前端来说

前端不需要花大量沟通时间来交流接口问题了，只需要看接口文档的描述即可
当后端接口变更时，只需要刷新下Swagger页面即可马上看到

快速入门

这里我们就用Knife4j为例

官网：https://doc.xiaominfo.com/knife4j/

一、加入依赖文件

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

二、添加配置类

basePackage包名记得修改成你自己的包名

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        //.title("swagger-bootstrap-ui-demo RESTful APIs")
                        .description("# swagger-bootstrap-ui-demo RESTful APIs")
                        .termsOfServiceUrl("http://www.xx.com/")
                        .contact("xx@qq.com")
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("2.X版本")
                .select()
                //这里指定Controller扫描包路径,自行记得修改！！！！
                .apis(RequestHandlerSelectors.basePackage("com.boss.demo.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

三、编写Controller类

@Api(tags = "用户模块")
@RestController
@RequestMapping("/user")
public class UserController {
    @ApiImplicitParam(name = "id", value = "用户ID", required = true)
    @ApiOperation(value = "用户信息")
    @GetMapping("/get")
    public ResponseEntity<String> getUserList(@RequestParam(value = "id") String id) {
        return ResponseEntity.ok("用户ID:" + id);
    }
}

之后打开http://localhost:8080/doc.html就可以进行测试了

在这里插入图片描述

常用注解

@Api(tags = “模块名称”)

表示标识这个类是swagger的资源，在每个Controller类上加上这个

@ApiOperation(value = “用户信息”,response = ResponseEntity.class)

表示一个Http接口请求，加上后，Swagger页面上就会多一条接口，指定response后，页面上会显示出你这个接口返回的类型数据结构

@ApiModel(description = “实体作用”)

用户描述一个实体类的作用，在页面上显示实体的地方，会带上这个描述信息

@ApiModelProperty

这个是需要放在实体类里属性上使用的

@Data
@ApiModel(description = "实体作用")
public class UserGetVo {
    @ApiModelProperty(value = "用户ID", required = true)
    private String id;
}

方法上的参数

在请求方法上加上注解的两种方式，@ApiImplicitParam和@ApiParam

方式一，在方法的上面增加注解@ApiImplicitParam

@ApiOperation(value = "方法参数")
@PostMapping("/get1")
@ApiImplicitParam(name = "userId", value = "用户ID")
public ResponseEntity<String> getUserList(String userId) {
    return ResponseEntity.ok("用户ID:" + userId);
}

方式二，在方法参数括号里，在变量前面增加@ApiParam

@ApiOperation(value = "方法参数")
@PostMapping("/get1")
public ResponseEntity<String> getUserList(@ApiParam(name = "userId", value = "用户名") String userId) {
    return ResponseEntity.ok("用户ID:" + userId);
}

扩展功能

认证登陆

Swagger页面现在访问都是没有限制的，谁都可以登陆进去看，这样很不安全，所哟我们可以配置认证登陆后，需要输入账号密码才可以登陆此网站，只需要在配置文件中配置以下信息即可

knife4j:
  # 开启增强配置 
  enable: true
　# 开启Swagger的Basic认证功能,默认是false
  basic:
      enable: true
      # Basic认证用户名
      username: test
      # Basic认证密码
      password: 123