How Mooncake Automated API Documentation and Built a Metadata Hub

Background

Many API management platforms focus on the consumption side, leaving documentation creation to developers who manually write files, which leads to stale, duplicated, or missing docs as the codebase grows.

API Documentation Organization Standards

Application Naming : To avoid divergent naming across domains, Mooncake aligns project names with the CMDB application name, reducing lookup difficulty and improving traceability.

Integrates with the release platform to fetch environment lists automatically.

Links with GitLab to bind documentation to iteration data.

Synchronizes with the gateway to auto‑associate routing groups.

Aggregates transaction‑gateway and APM data to enrich doc density.

Standardizing names created a unified naming scheme that simplified document discovery and boosted team collaboration.

Document Classification : Multi‑level classification was introduced to keep docs maintainable and tightly coupled to business domains such as merchant, customer service, supply chain, and transaction.

MooncakeUpload Idea Plugin

The plugin parses Java annotations and comments via IntelliJ Platform’s PSI (Program Structure Interface) to generate API docs in seconds, cutting manual effort dramatically.

Implementation Principle : PSI provides a syntax‑tree of the source file, exposing classes, methods, fields, and comments.

Core Implementation

Configuration : Reads a <component name="mooncakeUpload">…</component> file to obtain project token and user info. After version 2.0 the config was simplified to a single parameter, reducing the 80% configuration‑related failure rate.

Parameter Extraction : Uses PSI to locate the caret offset, resolve the selected class or method, then iterates over fields to collect type, name, and annotations. Example code:

// Get offset
PsiFile editorFile = e.getDataContext().getData(CommonDataKeys.PSI_FILE);
PsiElement referenceAt = psiFile.findElementAt(editor.getCaretModel().getOffset());

// Resolve class and method
PsiClass selectedClass = PsiTreeUtil.getContextOfType(referenceAt, PsiClass.class);
PsiMethod selectedMethod = PsiTreeUtil.getContextOfType(referenceAt, PsiMethod.class);

// Extract fields
PsiField[] fields = selectedClass.getAllFields();
for (PsiField field : fields) {
    PsiType type = field.getType();
    String name = field.getName();
}

Visualization Panel : Built with Java Swing, the panel lets users pick interfaces, classification, and requirement info, then uploads the generated JSON to Mooncake.

Result: Uploading a doc now takes only a few seconds; the plugin saves roughly 667 hours per iteration by automating doc creation.

GitLab MR Auto‑Parsing

Background : Manual uploads and gateway‑only checks miss many internal APIs (e.g., Dubbo, internal services) and cannot guarantee that post‑merge changes are reflected.

Implementation

Added a CI job that triggers on every merge to the release branch.

Job pulls the full source tree and all third‑party JARs (including de‑compiled sources) because compiled JARs lose comments.

Uses QDox to build a Java AST, then extracts Swagger or @RestController annotations to produce a JSON representation of HTTP APIs.

Compares extracted APIs with those already stored in Mooncake: if an API is missing, it is uploaded; if it exists but differs (e.g., parameter changes), the doc is updated.

Performance notes: parsing a 7k‑file project consumes ~3.5 minutes and significant memory; therefore the solution focuses on HTTP APIs and parses only the release branch to keep resource usage reasonable.

API Metadata Center

The center consolidates API information to support downstream use cases:

Debugging : Auto‑fills request fields from doc metadata, validates types, and pulls environment names from CMDB.

Mocking : Generates realistic mock data based on exact field definitions, including error‑code scenarios, enabling front‑end teams to test without waiting for back‑end implementations.

Metadata Platform : Exposes OpenAPI specs, field semantics, versioning, change rates, and health metrics to APM, traffic, and test automation platforms.

These capabilities reduce the time developers spend on manual debugging and mock setup, improve test coverage, and provide richer data for monitoring and quality‑control dashboards.

Future Outlook

As the business scales and micro‑service architectures proliferate, Mooncake will continue to expand its metadata hub to cover API health monitoring, automated testing integration, and tighter coupling with internal platforms, further lowering communication overhead and accelerating feature delivery.