Spring Boot集成Swagger2加入bootstrap-ui和knife4j

最新推荐文章于 2023-07-09 10:19:09 发布

一个不称职的程序猿

最新推荐文章于 2023-07-09 10:19:09 发布

阅读量598

点赞数

分类专栏： SpringBoot 文章标签： spring boot spring api java mybatis

本文链接：https://blog.csdn.net/qq_39035773/article/details/107466831

版权

SpringBoot 专栏收录该内容

6 篇文章 0 订阅

订阅专栏

swagger 简介

swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。
国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3）swagger2的包名为 io.swagger，而swagger3的包名为 io.swagger.core.v3。

maven依赖加入

<!-- Swagger API文档 -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-bean-validators</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.9.6</version>
</dependency>

Swagger2Config配置类

package com.governance.config;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import io.swagger.annotations.ApiOperation;

import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringBootVersion;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.*;

/**
 * Swagger2配置类
 * @author REID
 * @blog https://blog.csdn.net/qq_39035773
 * @date  2020年7月1日
 */
@Slf4j
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class Swagger2Config implements WebMvcConfigurer {

	/**
	 * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
	 */
	@Value("${swagger.enable:false}")
	private Boolean enable;

    /**
	 * 需要扫描的包
	 */
	@Value("${swagger.base-package:com}")
	private String basePackage;

	/**
	 * 企业名称
	 */
	@Value("${application.companyName:}")
	private String companyName;

	/**
	 * 企业地址
	 */
	@Value("${application.companyUrl:}")
	private String companyUrl;

	/**
	 * 企业邮箱
	 */
	@Value("${application.companyEmail:}")
	private String companyEmail;

	/**
	 * 项目应用名
	 */
	@Value("${application.name:系统}")
	private String applicationName;

	/**
	 * 项目版本信息
	 */
	@Value("${application.version:1.0}")
	private String applicationVersion;

	/**
	 * 项目描述信息
	 */
	@Value("${application.description:后台API接口}")
	private String applicationDescription;

	/**
	 * 显示swagger-ui.html文档展示页，还必须注入swagger资源：
	 */
	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
	}

	/**
	 * swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
	 * @return Docket
	 */
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				// 定义是否开启swagger，false为关闭，可以通过变量控制
				.enable(enable)
				// 将api的元信息设置为包含在json ResourceListing响应中。
				.apiInfo(apiInfo())
				.groupName(applicationName + "核心API")
				.select()
				//此包路径下的类，才生成接口文档(jeecg系统核心接口)
				.apis(RequestHandlerSelectors.basePackage(basePackage))
				//加了ApiOperation注解的类，才生成接口文档
	            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
				.paths(PathSelectors.any())
				.build()
				// 支持的通讯协议集合
				.protocols(newHashSet("https", "http"))
				// 授权信息设置，必要的header token等认证信息
				.securitySchemes(securitySchemes())
				// 授权信息全局应用
				.securityContexts(securityContexts());
	}

	/**
	 * 设置授权信息
	 */
	private List<SecurityScheme> securitySchemes() {
		return Collections.singletonList(new ApiKey("BASE_TOKEN", "token", "pass"));
	}

	/**
	 * 授权信息全局应用
	 */
	private List<SecurityContext> securityContexts() {
	    return Collections.singletonList(SecurityContext.builder().securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[] {new AuthorizationScope("global", "")}))).build());

	}

	@SafeVarargs
	private final <T> Set<T> newHashSet(T... ts) {
		if (ts.length > 0) {
			return new LinkedHashSet<>(Arrays.asList(ts));
		}
		return null;
	}

	/**
	 * api文档的详细信息函数,注意这里的注解引用的是哪个
	 * @return ApiInfo
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				// //大标题
				.title(applicationName + "后台服务API接口文档")
				// 版本号
				.version("Application Version: " + applicationVersion + ", Spring Boot Version: " + SpringBootVersion.getVersion())
//				.termsOfServiceUrl("NO terms of service")
				// 描述
				.description(applicationDescription)
				// 作者
				.contact(new Contact(companyName, companyUrl, companyEmail))
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
				.build();
	}

}

application.yml配置文件

application:
  companyName: XXXXXX
  name: 数据治理系统
  version: 1.0
  description: 后台生产API接口

swagger:
  enable: true
  production: false
  base-package: com.governance
  basic:
    enable: false
    username: test
    password: test1314

最后记得在启动类加@EnableSwagger2注解。

knife4j

随着项目的发展,面对越来越多的个性化需求,不得不编写后端Java代码以满足新的需求,在swagger-bootstrap-ui的1.8.5~1.9.6版本之间,采用的是后端Java代码和Ui都混合在一个Jar包里面的方式提供给开发者使用.这种方式虽说对于集成swagger来说很方便,只需要引入jar包即可,但是在微服务架构下显得有些臃肿。因此,项目正式更名为knife4j,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>${knife4j.version}</version>
</dependency>
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-ui</artifactId>
	<version>${knife4j.version}</version>
</dependency>

在本次项目中作者已经集成了springfox项目，所以不需要单独在引入Swagger相关依赖，避免出现依赖包冲突。

本次示例使用Spring Boot作为脚手架来快速集成Knife4j,Spring Boot版本2.4.5.RELEASE,Knife4j版本3.0.2

Swagger2Config配置类


import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringBootVersion;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.*;

/**
 * Swagger2配置类
 *
 * @author REID
 * @blog https://blog.csdn.net/qq_39035773
 * @date 2021年5月1日
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config implements WebMvcConfigurer {

    /**
     * 需要扫描的包
     */
    @Value("${application.base-package:com}")
    private String basePackage;

    /**
     * 企业名称
     */
    @Value("${application.companyName:}")
    private String companyName;

    /**
     * 企业地址
     */
    @Value("${application.companyUrl:}")
    private String companyUrl;

    /**
     * 企业邮箱
     */
    @Value("${application.companyEmail:}")
    private String companyEmail;

    /**
     * 项目应用名
     */
    @Value("${application.name:系统}")
    private String applicationName;

    /**
     * 项目版本信息
     */
    @Value("${application.version:1.0}")
    private String applicationVersion;

    /**
     * 项目描述信息
     */
    @Value("${application.description:后台API接口}")
    private String applicationDescription;

    /**
     * 显示swagger-ui.html文档展示页，还必须注入swagger资源：
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    /**
     * swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
     *
     * @return Docket
     */
    @Bean
    public Docket defaultApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 将api的元信息设置为包含在json ResourceListing响应中。
                .apiInfo(apiInfo())
                .groupName(applicationName + applicationVersion + "版本")
                .select()
                //此包路径下的类，才生成接口文档
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                //加了ApiOperation注解的类，才生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                // 授权信息设置，必要的header token等认证信息
                .securitySchemes(securitySchemes())
                // 授权信息全局应用
                .securityContexts(securityContexts());
    }

    /**
     * 设置授权信息
     */
    private List<SecurityScheme> securitySchemes() {
        return Collections.singletonList(new ApiKey("X-Access-Token", "X-Access-Token", "header"));
    }

    /**
     * 新增 securityContexts 保持登录状态
     */
    private List<SecurityContext> securityContexts() {
        return new ArrayList<SecurityContext> (
                Collections.singleton(SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build())
        );
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return new ArrayList<SecurityReference> (
                Collections.singleton(new SecurityReference("X-Access-Token", authorizationScopes)));
    }

    /**
     * api文档的详细信息函数,注意这里的注解引用的是哪个
     *
     * @return ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // //大标题
                .title(applicationName + "后台服务API接口文档")
                // 版本号
                .version("Application Version: " + applicationVersion + ", Spring Boot Version: " + SpringBootVersion.getVersion())
//				.termsOfServiceUrl("NO terms of service")
                // 描述
                .description(applicationDescription)
                // 作者
                .contact(new Contact(companyName, companyUrl, companyEmail))
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }

}

application.yml配置文件

application:
  base-package: com.xxx.xxx
  companyName: XXXXXX
  name: XXX系统
  version: 1.0
  description: 后台生产API接口

knife4j:
  # 开启增强配置
  enable: true
  # 开启Swagger的Basic认证功能,默认是false
  basic:
    enable: true
    # Basic认证用户名
    username: admin
    # Basic认证密码
    password: admin

到这里已经完成knife4j集成Spring boot了。

knife4j官网：https://doc.xiaominfo.com/knife4j/documentation/

一个不称职的程序猿

关注

0
点赞
踩
1

收藏

觉得还不错? 一键收藏
0
评论
Spring Boot集成Swagger2加入bootstrap-ui和knife4j

swagger 简介swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3）swagger2的包名为 io.swagger，而swagger3的包名为 io.swagger.core.v3。maven依赖加入<dependency>
复制链接

扫一扫