SpringBoot2整合Swagger增强解决方案knife4j

柔情只为你懂 2023-09-27 13:12 143阅读 0赞

## 一、Swagger介绍 ##

前后端分离开发模式中，api文档是最好的沟通方式。

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

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

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

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

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

## 二、集成knife4j ##

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。SpringBoot整合步骤如下：

#### 1.pom.xml文件里添加依赖 ####

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

#### 2.添加knife4j配置类 ####

在配置类包下添加此配置类

import io.swagger.annotations.Api;
    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;
    
    /**
     * knife4j配置信息
     */
    @Api(tags = "角色管理接口")
    @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.hj"))
                    .paths(PathSelectors.regex("/admin/.*"))
                    .build()
                    .globalOperationParameters(pars);
            return adminApi;
        }
    
        private ApiInfo adminApiInfo(){
    
            return new ApiInfoBuilder()
                    .title("后台管理系统-API文档")
                    .description("本文档描述了后台管理系统微服务接口定义")
                    .version("1.0")
                    .contact(new Contact("baidu", "https://baidu.com", "baidu@qq.com"))
                    .build();
        }
    }

#### 3.Controller层添加注解 ####

类与方法上均可用注解注解

@Api(tags = "角色管理接口")
    @RestController
    @RequestMapping("/admin/system/sysRole")
    public class SysRoleController {
    
        @Autowired
        private SysRoleService sysRoleService;
    
        @ApiOperation(value = "根据用户获取该用户角色数据")
        @GetMapping("/toAssign/{userId}")
        public Result toAssign(@PathVariable String userId) {
            Map<String, Object> roleMap = sysRoleService.getRolesByUserId(userId);
            return Result.ok(roleMap);
        }

#### 4.测试 ####

访问 [http://localhost:8080/doc.html ][http_localhost_8080_doc.html]

![17a3706c36d84d1b91914eb7ac80c566.png][]

#### 5.测试接口 ####

添加角色为例：

点开接口，选中要测试的方法，点击调试

![4221ed032aed4c2a9729d4be124634ca.png][]

添加数据，点击发送

![9ccad97874c240ed9d682d257a998cfc.png][]

[http_localhost_8080_doc.html]: http://localhost:8800/doc.html
[17a3706c36d84d1b91914eb7ac80c566.png]: https://img-blog.csdnimg.cn/17a3706c36d84d1b91914eb7ac80c566.png
[4221ed032aed4c2a9729d4be124634ca.png]: https://img-blog.csdnimg.cn/4221ed032aed4c2a9729d4be124634ca.png
[9ccad97874c240ed9d682d257a998cfc.png]: https://img-blog.csdnimg.cn/9ccad97874c240ed9d682d257a998cfc.png