项目引入Swagger及使用姿势
1.导入pom依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.2</version>
</dependency>
2.添加swagger配置类
package com.demo.config;
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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.EnableSwagger2;
import java.util.HashSet;
/**
* <p>
* swagger页面展示的配置
* </p>
*
* @author Toby
* @since 2020/5/13
*/
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Configuration {
@Bean
public Docket createRestApi() {
HashSet<String> contentType = new HashSet<>(1);
contentType.add("application/json");
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.consumes(contentType)
.produces(contentType)
.select()
// 扫描包路径
.apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("xxx-api文档")
.description("xxx-xx模块api文档")
.version("1.0")
.contact(new Contact("xxx项目组","","xxxx@xxx.com"))
.build();
}
}
注：basePackage要改为项目对应的controller目录路径，使用增强功能的话，需要在配置类上加@EnableKnife4j注解，并且在UI界面的个性化设置中开启增强功能。具体增强功能请移步至最后自行查看文档。
3.查看UI界面
启动项目后，在浏览器输入http://${host}😒{port}/doc.html
4.项目中可能会用到的增强功能
-
自定义文档
在resource目录下新建markdown文件夹，在目录下新建
.md结尾的file即可。在application.yml中加入以下配置knife4j: markdowns: classpath:markdown/*注意：自定义文档说明必须以
.md结尾的文件,其他格式文件会被忽略 -
访问权限控制-生产环境屏蔽Swagger所有资源接口
之前的项目如果想在正式环境配置中屏蔽
Swagger资源的话，是取的spring.profiles.active运行环境作判断，现在只需要在正式的application.yml中加入以下配置即可。knife4j: production: true -
访问页面加权控制
登录需要账号密码，提供简单的basic认证功能，在
application.yml中加入以下配置即可。knife4j: ## 开启Swagger的Basic认证功能,默认是false basic: enable: true ## Basic认证用户名 username: admin ## Basic认证密码 password: 123456
4.注意事项
-
依赖变更
ui前端界面显示的依赖更改，
com.github.xiaoymin下的springfox-swagger-ui最终版本为1.9.6，之后版本包名更改为knife4j，不同框架集成方式的pom依赖自行查看原文文档。 -
api分组相关，Docket实例不能延迟加载（目前应该用不到，具体多少个算多也不清楚，知道即可。）
springfox默认会把所有api分成一组，这样访问时会在同一个页面里加载所有api列表。这样，如果系统稍大一点，api稍微多一点，页面就会出现假死的情况，所以很有必要对api进行分组。api分组，定义多个RestApi即可，通过groupName作区分。
5.文档地址
knife4j使用教程：https://doc.xiaominfo.com/knife4j/
