Swagger 接口文档生成工具

Swagger

Swagger优点介绍

Swagger 在目前企业中作为前后端开发对接的技术已经得到了非常广泛的应用:

1. 后端开发人员只需要根据 OpenAPI 官方定义的注解就可以把接口文档非常丰富的呈现给前端接口对接人员。
2. 接口文档是随着代码的变动实时更新，
3. 提供了在线 HTML 文档辅助开发人员可以进行接口联调测试，

大大省去了技术人员写文档的烦恼，也提升了企业开发的效率，减少沟通成本。
官网：https://swagger.io/

Knife4j （SwaggerUI 的增强工具）

Knife4j 是一个 SwaggerUI 的增强工具，同时也提供了一些增强功能，使用 Java+Vue 进行开发，帮助开发者能在编写接口注释时更加完善.

knife4j官网：https://doc.xiaominfo.com/knife4j/

Knife4j使用

依赖导入

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>

<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
</dependency>

导入knife4j配置

在sky-server模块的WebMvcConfig复制以下代码

// 通过knife4j生成接口文档
@Bean
public Docket docket() {
    ApiInfo apiInfo = new ApiInfoBuilder()
        .title("苍穹外卖-管理后台")
        .version("2.0")
        .description("管理后台接口文档")
        .build();
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
        .groupName("管理端接口")
        .apiInfo(apiInfo)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.sky.web.admin"))
        .paths(PathSelectors.any())
        .build();
    return docket;
}

// 通过knife4j生成接口文档
@Bean
public Docket docket2() {
    ApiInfo apiInfo = new ApiInfoBuilder()
        .title("苍穹外卖-小程序端")
        .version("1.0")
        .description("小程序端接口文档")
        .build();
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
        .groupName("小程序端接口")
        .apiInfo(apiInfo)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.sky.web.app"))
        .paths(PathSelectors.any())
        .build();
    return docket;
}

设置静态资源映射

由于Swagger生成的在线文档中，涉及到很多静态资源，这些静态资源需要添加静态资源映射，否则接口文档页面无法访问。

因此需要在 WebMvcConfig类中的addResourceHandlers方法中增加如下配置

// 设置静态资源映射
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}

我们可以看到，在所有的Controller中提供的所有的业务增删改查的接口，全部都已经自动生成了，我们通过接口文档可以看到请求的url、请求方式、请求参数、请求实例、响应的参数，响应的示例。 并且呢，我们也可以通过这份在线的接口文档，对接口进行测试

**思考：**通过 Swagger 就可以生成接口文档，那么我们就不需要 Yapi 了？

Yapi官网： https://yapi.pro/

1. Yapi 是设计阶段使用的工具，管理和维护接口
2. Swagger 在开发阶段使用的框架，帮助后端开发人员做后端的接口测试

常用注解

在上面我们直接访问接口文档分类及接口描述都是Controller的类名(驼峰命名转换而来)及方法名，而且在接口文档中，所有的请求参数，响应数据，都没有中文的描述，并不知道里面参数的含义，接口文档的可读性很差。

接口测试配置

应用实例