（001）apidoc 的安装

安装

1.确定 node 和 npm 的匹配版本

node -v
 v10.14.1

# 切换node 版本
nvm list
nvm use 20.12.2

2.安装 apidoc。

npm install -g apidoc

3.生成文档：

apidoc -i ../  -o document/ -f  ".java$"

• -i ：指定扫描路径。
• -o：输出目录。
• -f：过滤文件。

apidoc.json

{
  "header": {
    "title": "说明",
    "filename": "header.md"
  },
  "footer": {
    "title": "",
    "filename": "footer.md"
  }
}

导出路由并排序

1.导出路由文件，并且将路由根据后面的描述排序：

package com.kd.shared.tool.apidoc;

import cn.hutool.core.io.FileUtil;
import cn.hutool.core.util.StrUtil;
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import com.alibaba.fastjson.serializer.SerializerFeature;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.File;
import java.nio.charset.StandardCharsets;
import java.time.LocalDateTime;
import java.util.*;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * 客户端路由生成文件 生成辅助工具。
 */
public class ApiDocCreator {
    private static final Logger LOGGER = LoggerFactory.getLogger(ApiDocCreator.class);
//    private String outputPath = "C:\\Users\\Administrator\\Desktop\\ApiDocCreator\\";
    private String outputPath = "E:\\data\\dyspace\\rhslg-client\\Miniwar\\Assets\\#A2_Scripts\\Network\\WebLogic\\Route\\";
    private String apidocjsonPath = "E:\\data\\dyspace\\richman-slg-server\\apidoc\\apidoc.json";
    private String scanPath = "";
    /**
     * routeName -> route description
     */
    Map<String, String> routeMap = new TreeMap<>();

    public static void main(String[] args) {
        ApiDocCreator apiDoc = new ApiDocCreator("E:\\data\\dyspace\\richman-slg-server\\game-server\\src\\main\\java\\com\\kd\\gameserver\\module").GenerateApiDoc();
        LOGGER.debug("output path: {}", apiDoc.outputPath);
    }

    public ApiDocCreator(String scanPath) {
        this.scanPath = scanPath;
    }

    public ApiDocCreator GenerateApiDoc() {
        CreateDirectory(outputPath);
        scanTable();
        CreateCSharpFile();
        writeDescriptionOrder();
        return this;
    }

    void writeDescriptionOrder(){
        if (!FileUtil.exist(apidocjsonPath))
            return;

        JSONObject jsonObject = JSON.parseObject(FileUtil.readString(new File(apidocjsonPath), StandardCharsets.UTF_8));
        if (jsonObject == null)
            return;

        List<String> groupNames = new ArrayList<>();
        groupNames.add("世界地图");
        groupNames.add("联盟");
        groupNames.add("资源");

        SortedSet<String> routeNames = new TreeSet<>(routeMap.values());
        routeNames.removeIf(item -> item.startsWith("推送"));
        List<String> nameList = new ArrayList<>(routeNames);
        nameList.add("推送");

        List<String> mergeList = new ArrayList<>();
        mergeList.addAll(groupNames);
        mergeList.addAll(nameList);

        jsonObject.put("order", mergeList);
        FileUtil.writeString(JSON.toJSONString(jsonObject, SerializerFeature.PrettyFormat), apidocjsonPath, StandardCharsets.UTF_8);
    }

    String getClientRouteFieldName(String route){
        String[] parts = route.split("\\.");
        return StrUtil.format("{}_{}",parts[1], StrUtil.upperFirst(parts[2]));
    }
    void CreateCSharpFile(){
        StringBuilder builder = new StringBuilder();
        builder.append("/// Auto Generate, Don't Modify!\n");
        builder.append(StrUtil.format("/// Date: {} \n\n", LocalDateTime.now()));
        builder.append("namespace WebLitchi\n");
        builder.append("{\n");
        builder.append("\tpublic partial class WsRoute\n");
        builder.append("\t{\n");
        routeMap.forEach((route, desc) -> {
            String[] parts = route.split("\\.");
            if (parts.length != 3)
                return;
            builder.append("\t\t/// <summary>\n");
            builder.append("\t\t/// " + desc + "\n");
            builder.append("\t\t/// </summary>\n");
            builder.append(StrUtil.format("\t\tpublic const string {} = \"{}\";\n", getClientRouteFieldName(route), route));
            builder.append("\n");
        });
        builder.append("\t}\n");
        builder.append("}\n");
        FileUtil.writeString(builder.toString(), StrUtil.format("{}/WsRoute.AutoGenerate.cs", outputPath), StandardCharsets.UTF_8);
    }

    void CreateDirectory(String path){
        if (!FileUtil.exist(path)){
            FileUtil.mkdir(path);
        }
    }

    Pattern pattern = Pattern.compile("\\s*\\*\\s*@api\\s+(.*)");
    void scanTable() {
        List<File> files = FileUtil.loopFiles(scanPath, pathname -> pathname.getName().endsWith("Handler.java"));
        files.forEach(item -> {
            Matcher matcher = pattern.matcher(FileUtil.readString(item, StandardCharsets.UTF_8));
            while (matcher.find()){
                String match = matcher.group(1);
                String[] parts = match.split("\\s");
                String route = StrUtil.trim(parts[0]);
                String desc = StrUtil.trim(parts[1]);
                routeMap.put(route, desc);
                LOGGER.debug("ROUTE {}, DESC {}", route, desc);
            }
        });
    }
}

2.导出的 order :

附录

[1]APIDOC