Springboot 快速生成项目API文档

## 1. 前言
Swagger是一个在线接口文档协议，通过一些注解快速生成API文档和调试功能，是一个增强版本的swagger的前端ui。
- 目前已经发行的Knife4j版本，Knife4j本身已经引入了springfox，开发者在使用时不用再单独引入Springfox的具体版本，否额会导致版本冲突。
- 在网关层聚合(例如gateway)时，必须禁用Knife4j的增强模式
- 使用Knife4j2.0.6及以上的版本，SpringBoot的版本必须大于等于2.2.x

## 2. 快速开始
2.1 引入maven依赖
```
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.5</version>
</dependency>
```

2.2 创建Swagger配置依赖
```
/**
 * description: swagger配置类
 * 访问 /doc.html    查看UI页面
 */
@EnableSwagger2
@EnableKnife4j
@Configuration
public class SwaggerConfiguration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("1.x")
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui RESTful APIs")
                .description("# swagger-bootstrap-ui-demo RESTful APIs")
                .termsOfServiceUrl("http://www.coldsmog.cn/")
                .contact(new Contact("coldsmog", "http://www.coldsmog.cn/", "coldsmog@foxmail.com"))
                .version("1.0")
                .build();
    }
}
```

2.3 写一个简单的Result类
```

/**
 * description: 统一返回类
 */
@ApiModel("统一返回类")
@Data
public class Result<T> implements Serializable {
    private static final long serialVersionUID = -3590682968045255221L;
    public final static int SUCCESS_CODE = 1;
    public final static int FAIL_CODE = 0;

@ApiModelProperty("程序执行结果，错误时为e.getmessage()")
    private String message;

@ApiModelProperty("true执行成功 false执行失败")
    private Boolean flag;

@ApiModelProperty("默认1为真,0为假，其余自定义")
    private Integer code;

@ApiModelProperty("成功时返回数据")
    private T data;

public Result(String message, Boolean flag, Integer code, T data) {
        this.message = message;
        this.flag = flag;
        this.code = code;
        this.data = data;
    }

public static <T> Result<T> success(T data) {
        return new Result<T>(null, true, SUCCESS_CODE, data);
    }

public static <T> Result<T> success(String message, T data) {
        return new Result<T>(message, true, SUCCESS_CODE, data);
    }

public static <T> Result<T> fail(String message) {
        return new Result<T>(message, false, FAIL_CODE, null);
    }

public static <T> Result<T> fail(Integer code, String message) {
        return new Result<T>(message, false, code, null);
    }

public static <T> Result<T> fail(Exception e) {
        return new Result<T>(e.getLocalizedMessage(), false, FAIL_CODE, null);
    }
}
```

2.4 写一个简单Controller
```
@Api(tags = "首页模块")
@RestController
public class IndexController {

@ApiImplicitParam(name = "name", value = "姓名", required = true)
    @ApiOperation(value = "向客人问好")
    @GetMapping("/sayHi")
    public Result<String> sayHi(@RequestParam(value = "name") String name) {
        return Result.success("Hi:" + name);
    }
}
```

## 3. 启动后访问 `/doc.html`

![](/media/202109/2021-09-17_173313.png)

![](/media/202109/2021-09-17_173354.png)

## 4. 资料来源
> 因本文档主要是SpringBoot 2.2.x以下使用的踩坑经验，高版本查看官网[knife4j](https://doc.xiaominfo.com/knife4j/documentation/)