一篇学会Swagger2（集成knife4j）_swagger2和knife4j

目录

一、Swagger2简介

1、前言

2、Open API是什么

3、Swagger简介

3.1、特性

3.2、组件

二、knife4j

三、内容

3.1、依赖

3.2、配置类

3.3、Controller层添加注解

3.4、测试

---

swagger是专门开发文档的，API文档(接口文档)，方便前后端工程师信息交互

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

一、Swagger2简介

1、前言

接口文档对于前后端开发人员都十分重要，
尤其近几年流行前后端分离接口文档又变成重中之重，
接口文档固然重要，但是由于项目周期等原因，
后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致
 
很多人员会抱怨别人写的接口文档不规范不及时更新，
但是当自己写的时候确实最烦去写这个文档，
这种痛苦只有亲身经历才会牢记于心，
如果接口文档可以实时动态生成，就不会出现上面问题
 
Swagger可以完美解决上面的问题

2、Open API是什么

Open API规范以前叫Swagger规范，是REST API 的API描述格式

Open API文件允许描述整个API，包括：

• 每个访问地址的类型。POST(写->post增,put改,delete删)或GET(读)。
• 每个操作的参数。包括输入输出参数
• 认证方法。
• 连接信息，声明，使用团队和其他信息。

Open API 规范可以使用YAML(树状)或JSON格式进行编写。这样更利于我们和机械进行阅读

 Open API规范(OAS)为RUST API定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，消费者可以使用最少的实现逻辑来理解远程服务并与之交互。

然后，文档生成工具可以使用Open API来定义显示API，使用各种编程语言生成服务器和客户端的代码生成工具，测试工具以及其他用例。

3、Swagger简介

Swagger是一套围绕open的开源工具，可以帮助设计，构建，记录和使用REST API。

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

3.1、特性

1、及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)

2、规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)

3、一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)

4、可测性 (直接在接口文档上进行测试，以方便理解业务)

3.2、组件

Swagger Editor：基于浏览器编辑器，可以在里面边写OpenAPI规范，类似Markdown具有实时预览描述文件的功能。(偶然会在配置中出现，通过配置的方式可以实现定制化的文档显示，用的比较少，因为还要程序员自己写)

Swagger UI：将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。(主要用于读，常见，可以将代码中嵌入的Swagger读出来也就是注解)

Swagger Codegen：将Open API规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。

Swagger Inspector：和Swagger UI有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。(类似ui加了过程记录)

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

使用Swagger，就是把相关的信息存储在它定义的描述文件里面(yml或json格式)，再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

二、knife4j

文档地址：Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

knife4j属于service模块公共资源，因此我们集成到service-uitl模块

三、内容

3.1、依赖

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

3.2、配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
 
import java.util.ArrayList;
import java.util.List;
 
/**
 * @author 
 * @Description swagger2配置类
 * @date
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
 
    @Bean
    public Docket adminApiConfig(){
        List<Parameter> pars = new ArrayList<>();
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name("token")
                .description("用户token")
                .defaultValue("")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(tokenPar.build());
        //添加head参数end
 
        Docket adminApi = new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .apis(RequestHandlerSelectors.basePackage("com.xx"))
                .paths(PathSelectors.regex("/admin/.*"))
                .build()
                .globalOperationParameters(pars);
        return adminApi;
    }
 
    private ApiInfo adminApiInfo(){
 
        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("xx", "http://xx.com", "xx@qq.com"))
                .build();
    }
 
}

3.3、Controller层添加注解

package com.lhw.controller;
 
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.lhw.exception.lhwException;
import com.lhw.model.system.SysRole;
import com.lhw.model.vo.SysRoleQueryVo;
import com.lhw.result.Result;
import com.lhw.service.SysRoleService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import org.yaml.snakeyaml.events.Event;
 
import java.util.List;
 
/**
 * @author xx
 * @Description
 * @date 
 */
@Api(tags = "角色管理接口")
@RestController
@RequestMapping("/admin/system/sysRole")
public class SysRoleController {
 
    /**
     * http://localhost:8800/doc.html
     */
 
    @Autowired
    private SysRoleService sysRoleService;
 
    /**
     * 批量新增
     * @param sysRoleList
     *    @RequestBody(json中的数组格式 -》 java中的list集合)
     * @return
     */
    @ApiOperation("批量新增角色接口")
    @PostMapping("saveBatch")
    public Result saveBatch(@RequestBody List<SysRole> sysRoleList){
        boolean isSuccess = sysRoleService.saveBatch(sysRoleList);
        if (isSuccess){
            return Result.ok();
        }
        else {
            return Result.fail();
        }
    }
 
 
}

3.4、实体类层添加注解

 
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableName;
import com.lhw.model.base.BaseEntity;
import io.swagger.annotations.ApiModelProperty;
import lombok.Builder;
import lombok.Data;
 
 
@Data
@Builder
@TableName("sys_role")
public class SysRole extends BaseEntity {
	
	private static final long serialVersionUID = 1L;
 
	@ApiModelProperty(value = "角色名称")
	@TableField("role_name")
	private String roleName;
 
	@ApiModelProperty(value = "角色编码")
	@TableField("role_code")
	private String roleCode;
 
	@ApiModelProperty(value = "角色描述")
	@TableField("description")
	private String description;
 
}

3.4、测试

测试地址http://localhost:8800/doc.html