Design and Implementation of a Code‑Centric Automated API Documentation Management Platform

The industry offers many excellent API documentation management solutions, most of which are integrated via IDE or Maven plugins. This article introduces NetEase Cloud Music's self‑developed, code‑relationship‑based, centralized, and automated API documentation management platform.

Background

With the rise of micro‑services and API‑driven front‑back collaboration, tools such as NEI, Swagger, YAPI, and Smart‑Docs have greatly improved development efficiency. However, evolving development processes have raised new requirements that the existing NEI platform can no longer meet, including heavy reliance on manual updates, low integration with development workflows, and a severe separation between API documentation and source code.

To address these issues, a new platform is proposed to standardize APIs, enhance lifecycle management, and tightly integrate with the development process.

Idea & Solution

Idea

The platform must ensure documentation accuracy while reducing developers' maintenance effort. Key challenges include:

Eliminating the gap between documentation and code—using Javadoc annotations provides a non‑intrusive, standard way to extract documentation directly from source code.

Creating and updating documentation quickly—leveraging GitLab webhooks to receive commit information enables incremental parsing and avoids full‑code re‑processing.

Handling incomplete information in incremental commits—by managing relationships (API‑to‑model, model‑to‑model) in a graph database, the system can retrieve the full impact scope of a change.

Thus, a code‑centric, AST‑based API documentation solution is adopted.

Overall Architecture

The overall scheme (illustrated in the accompanying diagram) consists of code scanning, relationship extraction, incremental analysis, and documentation generation.

Key Processes

New applications are fully scanned to build a baseline code relationship graph; subsequent changes are scanned incrementally via GitLab pushes.

Incremental analysis extracts basic change information, then expands it using the code relationship graph to obtain the complete impact range, updating the graph each time.

Full impact analysis derives complete API change details and updates the API documentation.

The updated documentation is compared against the previous version to produce a diff table for downstream consumers.

Stakeholders are identified through the relationship between code, applications, and requirements, and notifications are sent.

Relationship Management

Effective relationship management is crucial. A graph database stores two main types of relationships:

API node ↔ data model node (e.g., request, response).

Data model node ↔ data model node (e.g., field, association, inheritance).

All nodes carry branch attributes, enabling distinction between baseline (master) and development (dev) branches. The diagram below illustrates how relationships are maintained across branches.

Feature Demonstration

API Documentation Details

(Screenshots omitted.)

API Documentation Change Content

(Screenshots omitted.)

API Documentation Change Notification

(Screenshots omitted.)

Practical Issues Encountered

Source‑code parsing cannot resolve third‑party package references, leading to missing documentation. The team standardized branch naming across repositories to match globally, handling rare path collisions with special rules.

While the API standard discourages non‑standard structures, map‑type fields are sometimes unavoidable. A custom parsing logic was introduced to handle annotated map entries, as shown below: @Data public class AppDTO { /** * 应用id */ private Integer id; /** * 测试map， * * @OxLink key1 描述1 {@link CanvasDTO} * @OxLink key2 描述2 {@link AppDTO} * @OxLink key3 描述3 {@link ComponentDTO} */ private Map addedMap; }

Conclusion

This code‑centric, centralized API documentation management practice brings several benefits: developers only need to modify Javadoc comments to update documentation automatically, most updates complete within 30 seconds, and keeping API information in code ensures consistency between documentation and implementation.

Final Note

For more positions, visit NetEase's recruitment site: https://hr.163.com/