# 配置接口文档 Swagger 和 Knife4j 教程

这里介绍了如何配置 Swagger 和 Knife4j 3.0 版本，强烈建议大家使用 Knife4j ，因为它的前身是 swagger-bootstrap-ui ，是在 Swagger 的基础上进行了界面的优化，使用起来比 Swagger 舒服了太多

# 配置 Swagger

首先在 pom.xml 中加入依赖

springboot 2.2.x 以下版本和 2.2.x 以上版本使用依赖不同

<!--如果使用的springboot是 2.2.x 以下版本，需要同时配置springfox-swagger2 和 springfox-swagger-ui-->
 <dependencies>
	<dependency>
	    <groupId>org.springframework.boot</groupId>
	    <artifactId>spring-boot-starter-web</artifactId>
	    <version>2.1.3.RELEASE</version>
	</dependency>
    
	<dependency>
	     <groupId>io.springfox</groupId>
	     <artifactId>springfox-swagger2</artifactId>
	     <version>2.9.2</version> <!-- 这是一个与Spring Boot 2.1.x兼容的版本 -->
	 </dependency>
	 <dependency>
	     <groupId>io.springfox</groupId>
	     <artifactId>springfox-swagger-ui</artifactId>
	     <version>2.9.2</version> <!-- 保持与springfox-swagger2的版本一致 -->
	 </dependency>
</dependencies>

 <!-- 如果使用的springboot是 2.2.x 以上版本，可以直接引入springfox-boot-starter-->
dependencies>
	<dependency>
	    <groupId>org.springframework.boot</groupId>
	    <artifactId>spring-boot-starter-web</artifactId>
	    <version>2.2.13.RELEASE</version>
	</dependency>
    
	<dependency>
	    <groupId>io.springfox</groupId>
	    <artifactId>springfox-boot-starter</artifactId>
	    <version>3.0.0</version>
	</dependency>
</dependencies>

加入配置文件

	package com.example.demo.config;

	import io.swagger.annotations.ApiOperation;
	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.oas.annotations.EnableOpenApi;
	import springfox.documentation.service.ApiInfo;
	import springfox.documentation.service.Contact;
	import springfox.documentation.spi.DocumentationType;
	import springfox.documentation.spring.web.plugins.Docket;

	@EnableOpenApi // 开启 Swagger 自定义接口文档
	@Configuration // 相当于 Spring 配置中的 & lt;beans>
	public class SwaggerConfig {
	// 读取 yaml 中的配置
	@Value("${swagger.enable}")
	private Boolean enable;

	@Bean // 相当于 Spring 配置中的 & lt;bean>
	public Docket createRestApi() {
	return new Docket(DocumentationType.OAS_30)
	// 配置 swagger 是否生效
	.enable(enable)
	.apiInfo(apiInfo())
	.select()
	.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
	// .apis (RequestHandlerSelectors.basePackage ("com.yourcompany.yourproject.controller")) // 替换为你的 controller 包路径
	.paths(PathSelectors.any())
	.build();
	}
	// API 基础信息定义（就是更新 Swagger 默认页面上的信息）
	private ApiInfo apiInfo() {
	return new ApiInfoBuilder()
	.title("Swagger3接口文档测试")
	.description("这里是文档描述")
	.contact(new Contact("小盛", "网址", "邮箱"))
	.version("v1.0")
	.build();
	}
	}

创建一个 Controller

	@RestController
	@RequestMapping(value = "/api/v2/user", produces = MediaType.APPLICATION_JSON_VALUE)
	@Api(tags = "用户管理")
	public class User {

	@GetMapping
	@ApiOperation(value = "分页查询")
	public String page(){
	return "嘿嘿";
	}

	@GetMapping("/haha")
	@ApiOperation(value = "分页查询2")
	public List<UserEntity> getData(){
	List<UserEntity> list = new ArrayList<>();
	list.add(new UserEntity().setName("花花").setSex("男"));
	list.add(new UserEntity().setName("小王").setSex("女"));
	return list;
	}
	}

打开网址 http://localhost:8080/swagger-ui/index.html 即可看到如下接口文档界面
其中 ip 和端口设置为你自己的即可

yaml 配置，如果上生产了需要禁用 swagger，则改为 false 即可：

	#是否激活 swagger true or false
	swagger:
	enable: true

# 配置 Knife4j（强烈推荐）

Knife4j 使用文档

友情提示

1、目前已经发行的Knife4j版本，Knife4j本身已经引入了springfox，开发者在使用时不用再单独引入Springfox的具体版本，否额会导致版本冲突。另外在网关层聚合(例如gateway)时，必须禁用Knife4j的增强模式

2、使用Knife4j2.0.6及以上的版本，Spring Boot的版本必须大于等于2.2.x

3、微服务聚合组件Knife4jAggregation强势发布，聚合OpenAPI文档太简单了,详见文档

4、Knife4j独立运行版本Knife4jAggregationDesktop强势发布,使用Knife4j渲染OpenAPI文档很简单,详见文档

pom.xml 加入依赖

	<!-- 跟 swagger 类似，支持 springboot 2.2.x 以上版本 -->
	<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>3.0.2</version>
	</dependency>

配置文件

	package com.example.demo.config;

	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.Contact;
	import springfox.documentation.spi.DocumentationType;
	import springfox.documentation.spring.web.plugins.Docket;
	import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

	@Configuration
	@EnableSwagger2WebMvc // 貌似被弃用，可以替换为 @EnableSwagger2
	public class Knife4jConfiguration {

	@Value("${swagger.enable}")
	private Boolean enable;

	@Bean(value = "defaultApi2")
	public Docket defaultApi2() {
	Docket docket=new Docket(DocumentationType.SWAGGER_2)
	.enable(enable)
	.apiInfo(
	new ApiInfoBuilder()
	//.title("swagger-bootstrap-ui-demo RESTful APIs")
	.description("# swagger-bootstrap-ui-demo RESTful APIs")
	.termsOfServiceUrl("http://www.xx.com/")
	.contact(new Contact("小盛", "123", "504040410@qq.com"))
	.version("1.0")
	.build()
	)
	// 分组名称
	.groupName("2.X版本")
	.select()
	// 这里指定你自己的 Controller 扫描包路径
	.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
	.paths(PathSelectors.any())
	.build();
	return docket;
	}
	}

编写 Controller

	@RestController
	@RequestMapping(value = "/api/v2/user", produces = MediaType.APPLICATION_JSON_VALUE)
	@Api(tags = "用户管理")
	public class User {

	@GetMapping
	@ApiOperation(value = "分页查询")
	public String page(){
	return "嘿嘿";
	}

	@GetMapping("/haha")
	@ApiOperation(value = "分页查询2")
	public List<UserEntity> getData(){
	List<UserEntity> list = new ArrayList<>();
	list.add(new UserEntity().setName("花花").setSex("男"));
	list.add(new UserEntity().setName("小王").setSex("女"));
	return list;
	}
	}

访问 http://localhost:8080/doc.html#/home，ip 和端口改为你自己的，接口文档界面如下

yaml 配置，如果上生产了需要禁用 swagger，则改为 false 即可：

	#是否激活 swagger true or false
	swagger:
	enable: true

# 注解使用

@Api：用在 controller 类上，描述 API 接口，例：

@Api(tags = "用户管理")

@ApiOperation：用在 controller 的方法上，例：
PS：如果接口使用了 @RequestMapping 的话它会生成 get，post，put，delete 不同的请求方式的接口，所以最好指定 RestFull

@ApiOperation(value = "分页查询")

@ApiModel：用在实体类上
@ApiModelProperty：描述对象属性

	@Data
	@Accessors(chain = true)// 这个是 lombok 注解
	@ApiModel("用户实体类")
	public class UserEntity {

	@ApiModelProperty("名称")
	private String name;
	@ApiModelProperty("性别")
	private String sex;
	}

以下三个注解实际上很少用

@ApiImplicitParams：描述接口参数
@ApiResponses：描述接口响应
@ApiIgnore：忽略不显示接口参数

# 用 Swagger3 替换 Swagger2 注释

(它已经包含在 springdoc-openapi-ui 依赖项中)。swagger3 注释的包是 io.swagger.v3.oas.annotations

# 依赖项：

swagger3 只需要一个依赖即可

	<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
	<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-boot-starter</artifactId>
	<version>3.0.0</version>
	</dependency>

# Swagger2 到 Swagger3 的变化规则：

@Api → @Tag
 
@ApiIgnore → @Parameter(hidden = true)或@Operation(hidden = true)或@Hidden
 
@ApiImplicitParam → @Parameter
 
@ApiImplicitParams → @Parameters
 
@ApiModel → @Schema
 
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
 
@ApiModelProperty → @Schema(description = "描述")
 
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
 
@ApiParam → @Parameter
 
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")