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

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

时间：2020-04-25 11:46:29

一、原由

最近在做一个小项目的开入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;@Autowiredpublic SwaggerConfiguration(TypeResolver typeResolver, OpenApiExtensionResolver openApiExtensionResolver) {this.typeResolver = typeResolver;this.openApiExtensionResolver = openApiExtensionResolver;}@Beanpublic 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("/licenses/LICENSE-2.0").contact(new Contact("作者", "", "xxx@")).build();}}

application.yml

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

文档结构位置

源码

/leopast/knife4j-demo.git