参考文献：
1. 概述
在前后端大行其道的今天，前端与后端如何更高效的交互，其中很重要的一个环节就是编写 api 的接口文档，但是，这个工作由谁来做，怎么来做，似乎很难来回答，那么，有没有一种技术或者是软件，能够帮我们自动生成 api 的接口文档，答案是肯定的，他就是 Swagger UI ，一个专注自动生成在线 api 文档的工具。
2. Swagger UI 的使用
2.1 导入所需依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
2.2 基本配置
@Configuration
@EnableSwagger2 // 开启框架功能
public class SwaggerUIConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 为当前包下controller生成API文档
.apis(RequestHandlerSelectors.basePackage("com.caochenlei.controller"))
// 为有@Api注解的Controller生成API文档
// .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
// 为有@ApiOperation注解的方法生成API文档
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
//配置项目基本信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("请填写项目标题")
.description("请填写项目描述")
.termsOfServiceUrl("http://www.example.org")
//请填写项目联系人信息（名称、网址、邮箱）
.contact(new Contact("tom", "tom.com", "tom@163.com"))
//请填写项目版本号
.version("1.0")
.build();
}
}
测试代码
@RestController
//该注解用于描述当前控制器的作用
@Api(tags = "Hello控制器")
public class HelloController {
/**
* 第一种描述方式，使用注解：@ApiOperation、@ApiParam
*
* @param name
* @param age
* @return
*/
@GetMapping("/hello1")
// value：描述该方法的作用，notes：描述该方法的备注信息
@ApiOperation(value = "输出用户信息", notes = "返回一个拼接的字符串")
public String hello1(
// name：参数名称，value：参数说明，required：是否必填
@ApiParam(name = "name", value = "名称", required = true) @RequestParam("name") String name,
@ApiParam(name = "age", value = "年龄", required = true) @RequestParam("age") Integer age) {
return name + ":" + age;
}
/**
* 第二种描述方式，使用注解：@ApiOperation、@ApiImplicitParams、@ApiImplicitParam
*
* @param name
* @param age
* @return
*/
@GetMapping("/hello2")
@ApiOperation(value = "输出用户信息", notes = "返回一个拼接的字符串")
//该注解用于在方法上描述该方法的参数
@ApiImplicitParams({
// name：参数名称，value：参数说明，required：是否必填
@ApiImplicitParam(name = "name", value = "名称", required = true),
@ApiImplicitParam(name = "age", value = "名称", required = true)
})
public String hello2(@RequestParam("name") String name, @RequestParam("age") Integer age) {
return name + ":" + age;
}
@PostMapping("/hello3")
@ApiOperation(value = "输出用户信息", notes = "返回一个对象")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "名称", required = true),
@ApiImplicitParam(name = "age", value = "名称", required = true)
})
public User hello3(@RequestParam("name") String name, @RequestParam("age") Integer age) {
User user = new User();
user.setName(name);
user.setAge(age);
return user;
}
}
@ApiModel(value = "User类型", description = "这表示一个用户实体")
public class User {
@ApiModelProperty(name = "name", value = "名称", required = true)
private String name;
@ApiModelProperty(name = "age", value = "年龄", required = true)
private Integer age;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
}
打开文档页面： http://localhost:8080/swagger-ui.html
3. Swagger UI 注解
@Api：用在请求的类上，表示对类的说明
tags：用于描述当前类的作用
@ApiOperation：用在请求的方法上，表示对方法的说明
value：用于描述当前方法的作用
notes：用于描述当前方法的备注信息
@ApiParam：用在请求方法的参数上，表示对该参数的说明
name：参数名称
value：参数说明
required：参数是否必须传
defaultValue：参数的默认值
example：参数示例
@ApiImplicitParams：用在请求的方法上，表示该方法参数的说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，表示对该参数的说明
name：参数名称
value：参数说明
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path --> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数的类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
example：参数示例
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses注解中，一般用于表达一个错误的响应信息
code：错误码，例如400
message：错误信息，例如"请求参数未知"
response：抛出异常的类
@ApiModel：用于实体类上，表示一个复杂类型的描述，可用作参数接收、可用作返回对象
value：实体类名称
description：实体类描述
@ApiModelProperty：用在属性上，描述响应类的属性
name：参数名称
value：参数说明
required：参数是否必须传
dataType：参数的类型，默认String，其它值dataType="Integer"
example：参数示例
4. Swagger UI 的美化
导入所需依赖： 只导入这一个就可以了，之前导入的那两个可以全部删掉了，其他代码均保持不变即可
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
打开文档页面： http://localhost:8080/doc.html
