有了 Swagger,再也不用写 API说明文档啦

spring boot 整合swagger2(knife4j-UI升级版

  • 前言
    • Swagger 是什么?
      • 1.作用:
      • 2.官网:[https://swagger.io](https://swagger.io/)
    • knife4j 是什么?
      • 1.作用:
      • 2.官网:[https://doc.xiaominfo.com](https://doc.xiaominfo.com/)
  • 整合
    • 一、pom.xml 引入 依赖
    • 二、创建swagger配置文件(swaggerConfig.java)
    • 三、启动项目,访问 [http://localhost:8089/doc.html](http://localhost:8089/doc.html) (请求的端口看自身情况,我项目配置的是8089)
  • 补充:
    • API排序需要开启 增强模式
    • 若无法访问或访问后API无法正常显示,原因有以下几点:
    • 效果图
    • 注解
    • 整合过程中遇到的问题:
    • 感谢大家的阅读,有收获?希望兄弟姐妹三叔六婶大姨大妈阿公阿婆来个三连击,给更多的同学看到这篇文章

前言

Swagger 是什么?

  • Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

1.作用:

  1. 启动项目后在线自动生成API文档
  2. 在线高效调试

2.官网:https://swagger.io

knife4j 是什么?

  • 为Java MVC框架集成Swagger的增强解决方案-前身是 swagger-bootstrap-ui
  • swagger-bootstrap-ui是springfox-swagger的增强UI实现,为Java开发者在使用Swagger的时候,能拥有一份简洁、强大的接口文档体验

1.作用:

  1. 接口排序
  2. 自定义文档说明
  3. 访问权限控制
  4. 请求参数缓存
  5. 调试动态请求参数
  6. 文档说明等

2.官网:https://doc.xiaominfo.com

整合

一、pom.xml 引入 依赖


		<dependency>
			<groupId>io.springfoxgroupId>
			<artifactId>springfox-swagger2artifactId>
			<version>2.9.2version>
			<exclusions>
			    <exclusion>
			        <groupId>io.swaggergroupId>
			        <artifactId>swagger-annotationsartifactId>
			    exclusion>
			    <exclusion>
			        <groupId>io.swaggergroupId>
			        <artifactId>swagger-modelsartifactId>
			    exclusion>
			exclusions>
		dependency>
		
		
        <dependency>
            <groupId>io.swaggergroupId>
            <artifactId>swagger-annotationsartifactId>
            <version>1.5.21version>
        dependency>
        
        <dependency>
            <groupId>io.swaggergroupId>
            <artifactId>swagger-modelsartifactId>
            <version>1.5.21version>
        dependency>

		
		<dependency>
			<groupId>io.springfoxgroupId>
			<artifactId>springfox-swagger-uiartifactId>
			<version>2.9.2version>
		dependency>
		<dependency>
			<groupId>com.github.xiaoymingroupId>
			<artifactId>knife4j-spring-boot-starterartifactId>
			<version>2.0.2version>
		dependency>

二、创建swagger配置文件(swaggerConfig.java)

@Configuration // 声明为配置文件,让spring加载
@EnableSwagger2 // 支持swagger2插件配置
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config {
     

	// apiInfo对象主要是设置我们api文档的标题,描述,访问的地址,创建者等信息
	@SuppressWarnings("deprecation")
	@Bean
	public ApiInfo apiInfo() {
     
		return new ApiInfoBuilder()
				.title("浓密秀发之谦先生的Api接口文档")
				.description("快速进行Api接口调试")
				.termsOfServiceUrl("127.0.0.1:8080")
				.contact("Qian")
				.version("1.0")
				.build();
	}

	/**
	 * 创建API
	 */
	@Bean
	public Docket createRestApi() {
     
		return new Docket(DocumentationType.SWAGGER_2)
				// .pathMapping("/dev-api")
				// 用来创建该API的基本信息,展示在文档的页面中(自定义展示的信息)
				.apiInfo(apiInfo())
				// 设置哪些接口暴露给Swagger展示
				.select()
				// 扫描所有有注解的api,用这种方式更灵活
				// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
				// 扫描指定包中的swagger注解
				.apis(RequestHandlerSelectors.basePackage("cn.timer.api"))
				// 扫描所有 .apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.any()).build()
				/* 设置安全模式,swagger可以设置访问token */
				.securitySchemes(securitySchemes()).securityContexts(securityContexts());
	}

	/**
	 * 安全模式,这里指定token通过Authorization头请求头传递
	 */
	private List<ApiKey> securitySchemes() {
     
		List<ApiKey> apiKeyList = new ArrayList<ApiKey>();
		apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
		return apiKeyList;
	}

	/**
	 * 安全上下文
	 */
	private List<SecurityContext> securityContexts() {
     
		List<SecurityContext> securityContexts = new ArrayList<>();
		securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth())
				.forPaths(PathSelectors.regex("^(?!auth).*$")).build());
		return securityContexts;
	}

	/**
	 * 默认的安全上引用
	 */
	private List<SecurityReference> defaultAuth() {
     
		AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
		AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
		authorizationScopes[0] = authorizationScope;
		List<SecurityReference> securityReferences = new ArrayList<>();
		securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
		return securityReferences;
	}

}

三、启动项目,访问 http://localhost:8089/doc.html (请求的端口看自身情况,我项目配置的是8089)

有了 Swagger,再也不用写 API说明文档啦_第1张图片

补充:

API排序需要开启 增强模式

有了 Swagger,再也不用写 API说明文档啦_第2张图片

若无法访问或访问后API无法正常显示,原因有以下几点:

  1. 路径 http://localhost:8089/doc.html 被拦截
  2. 静态资源被后端拦截,如 js、html等

效果图

有了 Swagger,再也不用写 API说明文档啦_第3张图片
有了 Swagger,再也不用写 API说明文档啦_第4张图片
有了 Swagger,再也不用写 API说明文档啦_第5张图片

注解

  • tag排序:
    @Api(tags = "1.0登录")
    @Api(tags = "2.0注册")

  • api排序:
    @ApiOperationSupport(order = 1)
    @ApiOperationSupport(order = 2)

整合过程中遇到的问题:

  • @ApiModelProperty注解example属性格式无法被解析
    @ApiModelProperty(value = "是否默认", example = "["0","1"]")
    example 的值 [“0”,“1”] 数组格式无法被解析,建议该为{}或字符串

感谢大家的阅读,有收获?希望兄弟姐妹三叔六婶大姨大妈阿公阿婆来个三连击,给更多的同学看到这篇文章

你的每一次回眸都是永恒,每一次鼓励都是我前进的动力,每一次分享都是对我的认可。

你可能感兴趣的:(springboot,swagger,Api,spring,boot,java,spring)