自动生成接口文档操作手册-526互联

API 文档自动化生成

版本说明

实测仅适用于 Spring 2.x 版本，Spring 3 需要额外配置

后端

创建一个 Spring Web 项目

项目初始化

src
- main
  - java
    - com.example
      - config
        
        Knife4jConfig.java
      - entity
        
        Entity.java
      - controller
        
        EntityController.java
      - Application.java
  - resource
    - application.yaml

项目依赖

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-test</artifactId>
  <scope>test</scope>
</dependency>

<dependency>
  <groupId>org.projectlombok</groupId>
  <artifactId>lombok</artifactId>
  <optional>true</optional>
</dependency>

Entity

@Data
@AllArgsConstructor
public class Entity {
    private int id;
    private String name;
}

EntityController

@RestController
@RequestMapping("/entity")
public class EntityController {
    @GetMapping("/get")
    public Entity getEntity() {
        Entity entity = new Entity(1, "Ba11ooner");
        return entity;
    }
}

API 文档生成插件

插件依赖

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

Knife4jConfig

@Configuration
@EnableSwagger2
@Profile("dev")
public class Knife4jConfig {
    @Bean
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        //TODO 配置项目信息
                        .title("project-backend")
                        .description("project-backend")
                        .version("1.0")
                        .build())
                .select()
                //TODO 指定 Controller 扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

Application

@SpringBootApplication
@Import(Knife4jConfig.class)
public class Application {

	public static void main(String[] args) {
		SpringApplication.run(ApiDocGeneratorBackendApplication.class, args);
	}

}

application.yaml

spring:
  #swagger 兼容性配置
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

前端

参考文档

项目初始化

创建一个 Vue 项目（仅以 Vue 为例，其他同理）

API 文档生成插件

依赖下载

cnpm i @umijs/openapi ts-node -D
cnpm i umi-request

生成脚本编写

根目录创建 openapi.config.ts

declare let require: any
const { generateService } = require('@umijs/openapi')

generateService({
    requestLibPath: "import { request } from 'umi'",
    schemaPath:'http://localhost:8080/v3/api-docs',
    serversPath: './src/servers',
})

生成脚本的配置与执行

配置 package 脚本

"scripts": {
  "openapi": "ts-node openapi.config.ts"
},

npm openapi

修改脚本编写

批量修改生成的文本，在根目录下创建文件 openapi.replace.bat or openapi.replace.sh

Windows：bat 实现批处理

@echo off
chcp 65001 > nul

setlocal enabledelayedexpansion

set "old_text=import { request } from 'umi';"
set "new_text=import request from 'umi-request';"

set "file_pattern=src/servers/api/*.ts"

for %%f in (%file_pattern%) do (
    set "old_file=%%~nf%%~xf"
    set "new_file=%%~nf_output%%~xf"

    set "input_file=src/servers/api/%%~nf%%~xf"
    set "output_file=src/servers/api/%%~nf_output%%~xf"

    (for /f "usebackq delims=" %%a in (!input_file!) do (
        set "line=%%a"
        set "line=!line:%old_text%=%new_text%!"
        echo(!line!
    )) > !output_file!

    (for /f "usebackq delims=" %%a in (!output_file!) do (
        set "line=%%a"
        set "line=!line!"
        echo(!line!
    )) > !input_file!

    del "%cd%\src\servers\api\%%~nf_output%%~xf"
)

Unix：shell 实现批处理

#!/bin/bash

old_text="import { request } from 'umi';"
new_text="import request from 'umi-request';"
file_pattern="src/servers/api/*.ts"

for file in $file_pattern; do
    old_file=$(basename "$file")
    new_file="${old_file%.*}_output.${old_file##*.}"

    input_file="src/servers/api/$old_file"
    output_file="src/servers/api/$new_file"

    sed -e "s/$old_text/$new_text/g" "$input_file" > "$output_file"
    mv "$output_file" "$input_file"
done

sh openapi.replace.sh

修改脚本的配置和执行

{
  "scripts": {
    "openapi-create": "ts-node openapi.config.ts",
    "openapi-replace": "openapi.replace.bat",
    "openapi": "npm run openapi-create && npm run openapi-replace"
  }
}

npm run openapi