聊聊接口文档的事儿

1、前言

大家好，欢迎来到我的吉鹿（记录）空间。

最近在做一个前后端分离的项目时，由于后端提供的 API 接口文档实在是一言难尽，导致了开发的效率大大降低。于是我出手了，我决定薅完我20几年的头发来肝一下接口文档。下面给大家介绍一下，如何正确的在自己的项目中使用接口文档。

2、简介

2.1、什么是接口文档？

接口文档又称为 API 文档，通常由开发人员一起规定的一种规范，一般由后端开发人员所编写的，用来描述系统所提供接口信息的文档。前端人员直接调用某一个接口就可以实现某一个业务流程所需要的数据等信息。

2.2、为什么要写接口文档？

项目开发过程中前后端开发人员更加方便。
项目迭代或者项目人员更迭时，方便后期人员的维护。
为测试人员进行接口测试提供便利。

3.3、接口文档如何选择？

一个合格的接口文档是十分重要的，规范的文档可以很大程度的提高工作效率，尤其是对于接口测试而言。

合格的接口文档包含了：项目介绍、业务介绍、环境介绍、项目设计的请求和各个请求方式的传参格式和请求内容以及返回值等。对于一个功能很多的项目来说，接口是非常多的，基本都是上千个，那么为了实现更好的文档管理和阅读的目的，就需要对接口文档根据模块进行划分，不同的模块的划分也有不同的要求。这些都是实现一个合格的接口文档所需要具备的条件。竟然一个接口文档需要花费如此功夫，那么如何编写合格的接口文档呢？

手写接口文档？不可能，这辈子都不可能！当然是用 Swagger 接口文档工具了

4.4、如何使用Swagger接口文档？

废话不多说？走，整点儿东西！

到官网去巴拉几下：http://swagger.io ，了解基本用法，如果有看不懂英文的小伙伴，我在下面贴心的为大家准备了 Swagger 基本的模板，下面就简单介绍下 Swagger 基本用法吧。

3、Swagger

3.1、准备阶段

先新建 Spring Boot 工程，然后引入依赖，只需要引入一个版本即可

<!-- Swagger2.9.2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- Swagger3.0.0 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

备注：项目使用的 Spring Boot 版本为 2.5.5，如果使用更高版本的 Spring Boot 需要在 application.yml 添加如下配置

spring:
    mvc:
        path match:
            matching-strategy: ant_path_matcher

3.2、配置 Swagger

新建 Swagger2Config.java

Swagger 配置参考：http://springfox.github.io/springfox/docs/current/#quick-start-guides

下面的配置方式不仅仅适用于 Swagger 2.9.2 也适用于 Swagger 3.0.0 版本，但是在3.0.0版本中有小部分做了修改，详细体现在代码中的注释处。

@Configuration
@EnableSwagger2  // 2
// @EnableOpenApi      // 3
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)  // 2
        // return new Docket(DocumentationType.OAS_30)  // 3
                .pathMapping("/")
                .enable(true)
                .host("localhost:8888")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.record.controller"))
                .paths(PathSelectors.any())
                .build()
                .protocols(newHashSet("https","http"))  // 2
                .securitySchemes(singletonList(apiKey()))
                .securityContexts(singletonList(securityContext()));
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("京茶吉鹿")
                .description("京茶吉鹿的Demo (SpringBoot2.5.5 + Swagger2.9.2)")
                .contact(new Contact("京茶吉鹿", "http:localhost:8888/doc.html", "jc.jingchao@qq.com"))
                .version("1.0.0")
                .termsOfServiceUrl("http://localhost:8888")
                .build();
    }
    private ApiKey apiKey(){
        return new ApiKey("Authorization", "Authorization", "Header");
    }
    private SecurityContext securityContext(){
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("/hello/.*"))
                .build();
    }
    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return singletonList(
                new SecurityReference("Authorization", authorizationScopes));
    }
}

3.3、访问接口文档

访问路径：

Swagger2.9.2 http://localhost:8888/swagger-ui.html
Swagger3.0.0 http://localhost:8888/swagger-ui/index.html

UI 界面如下

3.4、使用第三方的UI

虽然我们已经实现了Swagger接口文档，但是我们会发现 Swagger 自带的接口文档页面并不是我们喜欢的方式，我们可以使用第三方的界面，只需要引入下面的依赖，使用 http://localhost:8888/doc.html 就可以访问了

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

UI 界面如下

到此为止，一个完整的接口文档我们已经实现了。原生的 Swagger 就能够满足我们在开发中的使用，尽管我们也使用了第三方的 Swagger UI资源库来美化我们的界面，但是由于 swagger-bootstrap-ui 采用的是后端Java代码 + 前端Ui混合打包的方式，与今天的微服务架构显得格格不入，下面将使用 knife4j 来重新生成接口文档

如果你还不想使用 knife4j ，但是你中意与它的外表（UI界面）那么你可以使用引入下面的依赖来替换掉旧版本的 UI
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>3.0.3</version>
</dependency>
UI 界面如下，界面更加美观，神似一个后台管理系统的 UI 界面，同时还可以切换语言，更加值得称赞的是还能进行界面的个性化配置。唯一比较遗憾的是由于你只使用了新版的皮肤，不能体会到接口文档的一些增强特性。

看到此处如果 knife4j 仍然不能是你心动，那么你无需再看下面的内容了。

4、knife4j

4.1、什么是 knife4j？

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案，前身是swagger-bootstrap-ui，取名kni4j是希望她能像一把匕首一样小巧，轻量，并且功能强悍!

Knife4j 的主要两点：

🆕统一各个组件版本号,使用Knife4j时开发者根据需要自行引用,artifactId发生了变化
💯支持Spring Boot 3
🌼兼容适配springdoc-openapi底层框架，全面迁移到OpenAPI3的规范支持
🌿针对OpenAPI2(Swagger)规范提供了优化，开发者基于Spring Boot2版本可以无缝衔接
💪Knife4j-Desktop组件架构升级重写，新架构支持不同需求的OpenAPI规范进行聚合
💪提供官方Docker镜像服务，基于Knife4j可方便在云服务上进行使用
💥官网文档更新重写

Knife4j 架构

在这里插入图片描述

4.2、为什么使用 knife4j？

前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活
提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分

4.3、使用 knife4j

下面环境为 SpringBoot 3.0.1 + Knife4j 4.0.0 ，注意项目使用的JDK 版本需要在 17 以上。

引入 Knife4j 的 starter

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

引入Knife4j的 starter后，其余的配置，可以完全参考 springdoc-openapi 的项目说明，Knife4j只提供了增强部分，如果要启用Knife4j的增强功能，可以在配置文件中进行开启

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.xiaominfo.knife4j.demo.web
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

配置文件

@Configuration
public class SwaggerConfig {

    @Bean
    public GlobalOpenApiCustomizer orderGlobalOpenApiCustomizer() {
        return openApi -> {
            if (openApi.getTags()!=null){
                openApi.getTags().forEach(tag -> {
                    Map<String,Object> map=new HashMap<>();
                    map.put("x-order", RandomUtil.randomInt(0,100));
                    tag.setExtensions(map);
                });
            }
            if(openApi.getPaths()!=null){
                openApi.addExtension("record","1223456");
                openApi.getPaths().addExtension("x-record",RandomUtil.randomInt(1,100));
            }

        };
    }
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI().info(new Info()
                        .title("京茶吉鹿系统API")
                        .version("1.0.0")
                        .contact(new Contact().name("京茶吉鹿").email("jc.jingchao@qq.com").url("https://gitee.com/OHUHO"))
                        .description( "Knife4j集成springdoc-openapi示例")
                        .termsOfService("http://localhost:8888")
                        .license(new License().name("Apache 2.0")
                                .url("http://localhost:8888")));
    }
}

效果预览

在这里插入图片描述

4.4、使用增强特性

Knife4j 新版本已经将UI界面中的个性化配置剥离，只需要在后端进行配置即可。举个栗子，我们现在有这样一个需求，要给接口文档设置一个查看的权限（只有负责这个项目的前端人员才有资格查看），我们就可以为API文档设置密码，需要在配置文件中配置，如下

knife4j:
  # 开启增强配置 
  enable: true
　# 开启Swagger的Basic认证功能,默认是false
  basic:
      enable: true
      # Basic认证用户名
      username: test
      # Basic认证密码
      password: 123