springboot集成knife4j2.0.8实现自定义md文档及权限控制

码农记事本

已于 2022-03-12 23:36:57 修改

阅读量3.4k

点赞数

分类专栏： java笔记本文章标签：接口文档 knife4j

于 2021-01-28 15:50:05 首次发布

本文链接：https://blog.youkuaiyun.com/leopast/article/details/113341586

版权

java笔记本专栏收录该内容

32 篇文章

订阅专栏

本文档介绍了如何利用Knife4j的自定义文档功能，结合Spring Boot和Swagger，实现在项目开发中快速更新API接口文档。通过升级相关依赖，并配置SwaggerConfiguration，可以方便地管理和展示Markdown格式的接口文档，同时解决接口频繁变动带来的文档维护问题。在实际操作中需要注意解决依赖冲突，如需开启权限验证，可以启用基本认证功能。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

一、原由

最近在做一个小项目的开入API，文档是用vuepress写的静态md并发布。因为是项目刚起步，对接的接口也会经常改动，每次改动都要修改文档感觉太麻烦，就想到用knife4j来代替。但外部使用的接口和内部使用不一样，需要一些接入引导说明，比如API接入步骤、鉴权说明…等

重新翻了knife4j的文档发现2.x版本自2.0.7之后可以使用自定义文档的功能，自定义文档正好也是我喜欢的Markdown文件，再加一个权限验证，目前是很好的解决了我的问题。

效果：
在这里插入图片描述

二、开始

knife4j2.x版如果想实现自定义Markdown文档需要将版本升级2.0.7及以上

本次测试使用的springboot版本 2.0.3.RELEASE

需要用到的依赖

//swagger版本支持
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.10.5'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.10.5'
compile 'io.springfox:springfox-spring-webmvc:2.10.5'
//swagger注解无默认值错误忽略
compile group: 'io.swagger', name: 'swagger-annotations', version: '1.5.22'
compile group: 'io.swagger', name: 'swagger-models', version: '1.5.22'
//knife2.x版本
compile group: 'com.github.xiaoymin', name: 'knife4j-spring-boot-starter', version: '2.0.8'
//升级spring-plugin-core，否则会有冲突
compile 'org.springframework.plugin:spring-plugin-core:2.0.0.RELEASE'

SwaggerConfiguration

package com.only.oc.openapi.config;

import com.fasterxml.classmate.TypeResolver;
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;


@Configuration
@EnableSwagger2WebMvc
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {

    private final TypeResolver typeResolver;
    private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public SwaggerConfiguration(TypeResolver typeResolver, OpenApiExtensionResolver openApiExtensionResolver) {
        this.typeResolver = typeResolver;
        this.openApiExtensionResolver = openApiExtensionResolver;
    }


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.only.oc.openapi.api"))//扫描包
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//扫描在API注解的contorller
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//扫描带ApiOperation注解的方法
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions("2.X版本"));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("昂立课堂（开放API）")
                .description("昂立课堂开放平台")
                .version("v2.x")
                .license("Apache License Version 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .contact(new Contact("作者", "", "xxx@qq.com"))
                .build();
    }

}

application.yml

server:
  port: 8080

knife4j:
  enable: true
  # 生产环境屏蔽
  # production: true
  # 开启Swagger的Basic认证功能,默认是false
  basic:
    enable: true
    username: only
    password: only
  documents:
    -
      group: 2.X版本
      name: 另外文档分组请看这里
      locations: classpath:markdown/*
    - group: 2.X版本
      name: 接入方法
      locations: classpath:markdown/api.md

文档结构位置
在这里插入图片描述

源码

https://codechina.youkuaiyun.com/leopast/knife4j-demo.git

三、坑

当你一切准备就绪时就报如下错误
在这里插入图片描述
这里需要升级spring核心插件

compile 'org.springframework.plugin:spring-plugin-core:2.0.0.RELEASE'

原创文章未经本人许可，不得用于商业用途及传统媒体。转载请注明出处，否则属于侵权行为，谢谢合作！