参考文献：

整合篇：零基础学习与使用Swagger UI

mall整合Swagger-UI实现在线API文档

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