Qunar's API Standardization: From DDD to API Governance and QDoc Implementation

In early 2020, Qunar's ticket destination business group launched a major initiative to reshape its architecture by applying Domain‑Driven Design (DDD) internally and exposing services through standardized APIs externally. The goal was to reduce system complexity, improve team efficiency, and align business domains with clear service boundaries.

The evolution of Qunar's API tooling began with traditional wikis, progressed to YAPI (an open‑source platform introduced in 2018), and later incorporated Swagger annotations extended via Maven plugins to keep documentation synchronized with code. While wikis offered flexibility, they lacked enforceable standards; YAPI added testing and Restful compliance, and Swagger‑to‑YAPI bridges further reduced documentation drift.

Motivated by pandemic‑driven “internal strengthening”, Qunar recognized the need for API standardization to support DDD refactoring, hardware cost management, and automated regression testing of downstream services. Standardized APIs were required to be understandable, easily integrated, syntactically simple, manageable in execution, and readily applicable on platforms.

The theoretical basis stems from Jeff Bezos' 2002 system‑interface directive, which evolved into the SOA maturity model. This model mandates detailed interface specifications, evaluation criteria, IDE plugin support, and publishing system integration.

QDoc was built as a custom annotation framework to fit Qunar's engineering vocabulary (Domain, AppCode, Service, Interface, Parameter, Type). Key annotations include @QDomainDoc, @QAppcodeDoc, @QServiceDoc, @QInterfaceDoc, @QParamDocs, and related response annotations. The annotations allow engineers to describe API semantics directly in code, typically requiring only five minutes per medium‑complexity API.

Implementation steps covered:

4.1 Understandable specifications: Define a clear set of domain‑level terms and corresponding annotations.

4.2 Easy component integration: Provide a Maven plugin and annotation JAR; developers add them to their pom.xml and annotate services.

4.3 Simple syntax: Example annotation block for a Dubbo service with parameters and response definitions (shown in the original code snippet).

4.4 Manageable execution: Synchronize API definitions via Maven commands or the publishing system, ensuring documentation stays in sync with the master version.

4.5 Platform applicability: Embed YAPI within the App Management platform and extend it to support domain‑level API management, eventually exposing APIs through Qunar's gateway.

Key challenges included securing cross‑team resources, deciding between Design‑First and Code‑First approaches (Code‑First was chosen for domain APIs), preferring annotation‑based tools over comment‑based ones, and balancing full OpenAPI 3.0 compliance with existing platform capabilities.

Project outcomes demonstrated successful standardization across core, common, and supporting domains, reduced duplicated effort, and laid groundwork for future enhancements such as IDEA compliance plugins, comment‑mode support, client/server code generation, and exploration of alternative API portals like Knife4j.

In summary, Qunar's QDoc tool bridges code annotations to an open platform, enabling end‑to‑end API governance, fostering DDD adoption, and establishing a scalable, maintainable API ecosystem.