How Mooncake Automates API Docs, Builds a Metadata Hub, and Boosts Development Efficiency

Background

Many API management platforms focus on the consumption side, leaving documentation generation to developers and causing outdated or duplicated docs, which hampers front‑end mock data and overall API usability.

Mooncake API Documentation Maintenance

1. Documentation Organization Standards

Application Naming – Aligns with CMDB application names to reduce naming inconsistencies and simplify lookup.

Integrates with the release platform, CMDB, and gateway to automatically fetch environment lists.

Links with GitLab to bind documentation to iteration requirements.

Synchronizes with the gateway for route grouping.

Aggregates transaction gateway and APM data to enrich doc density.

Document Classification – Provides multi‑level classification (e.g., merchant, customer service, supply chain) to improve maintainability and reduce search difficulty.

2. MooncakeUpload Idea Plugin

Implementation Principle

Built on the IntelliJ Platform using PSI (Program Structure Interface) to parse the abstract syntax tree and extract classes, methods, fields, and annotations.

Core Implementation

Configuration – Reads plugin config via IntelliJ’s Virtual File System.

// 解析misc配置文件
File miscFile = new File(editor.getProject().getProjectFile().getPath());
Element miscElement = JDOMUtil.load(miscFile);

// 读取token
public static String getToken(Element element, PsiFile psiFile) {
    try {
        String token = getHistoryConfig(element, psiFile, MooncakeConstant.HistoryToken);
        if (token.equals("")) {
            token = getProjectConfig(element, psiFile, MooncakeConstant.Token);
        }
        if (token.equals("")) {
            Messages.showErrorDialog("请先去idea/misc.xml配置MooncakeUploadApi配置", "获取配置失败！");
        }
        return token;
    } catch (Exception e) {
        Messages.showErrorDialog("请先去idea/misc.xml配置MooncakeUploadApi配置", "获取配置失败！");
        return "";
    }
}

Configuration was simplified in version 2.0 to a single parameter:

<component name="mooncakeUpload">
    <option name="token">xxxxxxxx</option>
</component>

Parameter Extraction – Uses PSI to locate the selected class/method, retrieve annotations, and collect field information.

// 获取偏移量
PsiFile editorFile = e.getDataContext().getData(CommonDataKeys.PSI_FILE);
PsiElement referenceAt = psiFile.findElementAt(editor.getCaretModel().getOffset());

// 获取选中的类或者方法
PsiClass selectedClass = PsiTreeUtil.getContextOfType(referenceAt, PsiClass.class);
PsiMethod selectedMethod = PsiTreeUtil.getContextOfType(referenceAt, PsiMethod.class);

// 获取选中类下的所有方法
PsiMethod[] psiMethods = selectedClass.getMethods();
String apiValue = PsiAnnotationSearchUtil.getPsiParameterAnnotationParam(selectedClass, SwaggerConstants.API, "tags");
PsiClass psiClass = JavaPsiFacade.getInstance(project).findClass(psiParameter.getType().getCanonicalText(), GlobalSearchScope.allScope(project));
PsiField[] fields = psiClass.getAllFields();
PsiType type = field.getType();
String name = field.getName();

Visualization Panel – A Swing‑based GUI lets users select APIs, classification, and requirement info for upload.

Version Update Strategy – Private repository hosting enables automatic version checks and notifications.

Results

Rapid response to requirement changes via GitLab integration.

Significant reduction in documentation effort, saving ~667 hours per iteration.

Standardized API docs with visual upload workflow.

Documentation uploads per iteration now number in the thousands, dramatically improving maintenance efficiency.

3. GitLab MR Auto‑Parsing

Background

Manual uploads and gateway‑only checks lead to missing or stale docs, especially for internal or Dubbo APIs.

Implementation

Added a CI pipeline step that parses merged MR code, extracts Swagger/RestController annotations, and updates Mooncake accordingly.

Configured GitLab pipeline tasks (memory‑intensive for full code scans).

Handled large projects (7k+ files) with acceptable parsing times.

For third‑party JARs, the pipeline downloads source dependencies, decompiles them, and extracts annotations to ensure completeness.

JSONArray allModuleDepsTreeData = new JSONArray();
for (String fileDepTree : arrayListScannerMgr_Dep_Tree_POM) {
    JSONObject treeDependeces = dependcesParse(fileDepTree);
    allModuleDepsTreeData.add(treeDependeces);
}
// 过滤公司二方包
String group = nodeChild.getGroupId();
if (group.contains("xxx") || group.contains("xxxx")) {
    return true;
}
// 下载所有二方包
File tempFile = new File(jarScanPath.trim());
String fName = FilenameUtils.removeExtension(tempFile.getName());
fName = fName.replaceAll("-", "_");

Parsing uses QDox to build a Java AST and extract HTTP‑related classes:

// 初始化builder
JavaProjectBuilder builder = new JavaProjectBuilder();
builder.setEncoding(StandardCharsets.UTF_8.name());

// 读取所有class信息
builder.addSourceTree(new File(sourceDir));
Collection<JavaClass> classes = builder.getClasses();

// 过滤所有http接口
Collection<JavaClass> httpClasses = new ArrayList<>();
for (JavaClass javaClass : classes) {
  if (CommonHelper.isHttpClass(javaClass)) {
    httpClasses.add(javaClass);
  }
}

Parsed API data is compared with Mooncake; missing APIs are uploaded, existing ones are updated for consistency.

4. Mooncake API Metadata Center

Debug

Accurate field definitions enable auto‑filled request parameters, type validation, and environment‑aware debugging.

CMDB integration provides colored environment names.

Internal platform links improve signature and auth handling.

Mock

Front‑end can mock complete APIs during development, reducing dependency on back‑end delivery.

Input validation ensures data correctness before release.

Realistic mock data derived from actual API responses improves test fidelity.

API Metadata Platform

Aggregates API descriptions, specifications, stability metrics, examples, SDKs, and lifecycle data, feeding downstream systems such as APM, traffic monitoring, and automated test generation.

Provides OpenAPI specs for internal platforms.

Supplies field semantics to tracing systems.

Tracks change rates and debug success for quality dashboards.

By centralizing API information, Mooncake improves transparency, reliability, and ease of use across the organization.

5. Outlook

As business scales and micro‑service architectures grow, the API metadata center will continue to support automated testing, health monitoring, and further integration with downstream tools, reducing communication overhead and accelerating iteration cycles.