spring boot整合Knife4j

最新推荐文章于 2024-03-26 16:29:10 发布

风筝风筝等等我

最新推荐文章于 2024-03-26 16:29:10 发布

阅读量3.1k

点赞数 1

原文链接：https://blog.csdn.net/z17806289513/article/details/123659224

版权

微服务框架专栏收录该内容

13 篇文章 0 订阅

订阅专栏

文章目录

1、Knife4j简介
2、与 spring boot整合
3、其它功能
- 3.1 token认证参数设置
- 3.2 离线文档

1、Knife4j简介

以下内容来自Knife4j官网，贴一下官网地址：https://doc.xiaominfo.com/

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案
Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目
一开始项目初衷是为了写一个增强版本的swagger的前端ui,但是随着项目的发展,面对越来越多的个性化需求,不得不编写后端Java代码以满足新的需求,在swagger-bootstrap-ui的1.8.5~1.9.6版本之间,采用的是后端Java代码和Ui都混合在一个Jar包里面的方式提供给开发者使用.这种方式虽说对于集成swagger来说很方便,只需要引入jar包即可,但是在微服务架构下显得有些臃肿。
因此,项目正式更名为knife4j,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.
swagger-bootstrap-ui的所有特性都会集中在knife4j-spring-ui包中,并且后续也会满足开发者更多的个性化需求.
主要的变化是,项目的相关类包路径更换为com.github.xiaoymin.knife4j前缀,开发者使用增强注解时需要替换包路径
后端Java代码和ui包分离为多个模块的jar包,以面对在目前微服务架构下,更加方便的使用增强文档注解(使用SpringCloud微服务项目,只需要在网关层集成UI的jar包即可,因此分离前后端)
目前主要支持以Java开发为主,并且是依赖于大环境下使用的Spring MVC、Spring Boot、Spring Cloud框架.
当然,Knife4j也提供了离线版本,只要是符合Swagger的OpenAPI版本的规范JSON,都可以通过简单的配置进行适配，离线版本是适合于任何语言中使用Swagger的,非常的灵活、方便。

2、与 spring boot整合

2.1 引入依赖

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

2.2 配置Knife4j

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
 
    @Bean
    public Docket docket(Environment environment) {
        // 添加接口请求头参数配置 没有的话 可以忽略
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("token")
                .description("令牌")
                .defaultValue("")
                .modelRef(new ModelRef("string"))
                .parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否启动swagger 默认启动
                .enable(true)
                //所在分组
                .groupName("yvioo")
                .select()
                //指定扫描的包路径
                .apis(RequestHandlerSelectors.basePackage("com.xx.xx.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }
 
    private ApiInfo apiInfo() {
        Contact author = new Contact("姓名", "地址", "邮箱");
        return new ApiInfo(
                "xx文档",
                "xx文档",
                "1.0",
                "",
                author,
                "",
                "",
                new ArrayList()
        );
 
    }
 
}

2.3 放行Knife4j请求

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {
 
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

2.4 使用Knife4j注解标记接口

@Api(tags = "测试路由")
@RestController
@RequestMapping("/test")
public class TestController {
 
    @ApiOperation("测试get")
    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    @GetMapping("test1")
    public String test1(@RequestParam(value = "name") String name) {
        return "hello," + name;
    }
 
    @ApiOperation("测试post")
    @PostMapping("test2")
    public String test2(@RequestBody TestEntity testEntity) {
        return testEntity.getName() + ":" + testEntity.getSex();
    }
}

@ApiModel
@Data
public class TestEntity {
 
    @ApiModelProperty(value = "姓名", required = true)
    private String name;
    @ApiModelProperty(value = "性别", required = true)
    private String sex;
}