官网:https://swagger.io/
一、Swagger简介及SpringBoot集成
- 好撑世界上最流行的API框架
- Restful API文档在线自动生成工具 => API文档与API定义同步更新
- 直接运行,可以在线测试API接口
- 支持多种语言
SpringBoot集成:
-
导入依赖,新版本3.0.0开始只需要一个
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
-
编写配置类
package com.ola.config; /** * ClassName:SwaggerConfig Package:com.ola.config * * @date 2021/3/24 18:14 * @author morningj */ import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * @author ola * @date 2021年03月24日 18:14 */ @Configuration @EnableSwagger2 public class SwaggerConfig {}
二、配置Swagger
配置Swagger的Bean实例Docket
package com.ola.config;
/**
* ClassName:SwaggerConfig Package:com.ola.config
*
* @date 2021/3/24 18:14
* @author morningj
*/
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
/**
* @author ola
* @date 2021年03月24日 18:14
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置扫描接口及开关
.select()
.apis(RequestHandlerSelectors.basePackage("com.ola.controller"))
.build();
}
private ApiInfo apiInfo() {
return new ApiInfo(
"ola的swaggerAPI文档",
"这里是描述",
"1.0",
"http://localhost:8080/hello",
new Contact(
"ola", "https://blog.csdn.net/weixin_44791976?spm=1000.2115.3001.5343", "ola@123.com"),
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
}
}
三、配置扫描接口及开关
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置扫描接口及开关
.select()
// RequestHandlerSelectors:配置要扫描接口的方式
// basePackage:指定要扫描的包(推荐使用方式)
// any():扫描全部
// none():不扫描
// withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
// withMethodAnnotation:扫描方法上的注解的反射对象
// 例如:class--对应--RestController method--对应--GetMapping
.apis(RequestHandlerSelectors.basePackage("com.ola.controller"))
// 配置过滤路径
// .paths(PathSelectors.ant("/hello/**"))
// 配置启动关闭
.enabled(false)
.build();
}
四、配置API文档分组和接口注释
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 分组
.groupName("ola")
// 配置扫描接口及开关
.select()
.apis(RequestHandlerSelectors.basePackage("com.ola.controller"))
.build();
}
// 分组就多配几个Docket-Bean实例即可
TIPS:在正式发布的时候,关闭Swagger!可以设置多套环境,发布环境自动enabled=false!
依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
配置项
package com.ola.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
/**
* ClassName:SwaggerConfig Package:com.ola.config
*
* @author morningj
* @date 2021/4/3 08:50
*/
@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.ola.controller"))
.build();
}
private ApiInfo apiInfo() {
return new ApiInfo(
"基于关联图谱的学术检索系统",
"Controller接口文档",
"1.0",
"http://localhost:8080/login",
new Contact(
"ola",
"https://blog.csdn.net/weixin_44791976?spm=1000.2115.3001.5343",
"2317423960@qq.com"),
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
}
}