How cvs6/api-doc works
Project Identification
• This is a Java-based annotation-driven API documentation generation tool. Its main purpose is to scan Java code (using custom annotations like @Api, @ApiAction, etc.), generate JSON representations of API definitions, and then serve these to a front-end built in Angular.
• The tool is built to work with any Java project (using Spring or Spring Boot) and provides an automated way to generate and display API documentation with built-in support for complex request/response structures.
Components
a. Core Modules and Packages:
– API Annotation Module:
• Located in packages such as com.apidoc.annotation.
• Contains key annotations (Api, ApiAction, ApiReqParams, ApiRespParams, etc.) that mark the code for documentation.
– API Model/Bean Module:
• Found in com.apidoc.bean.
• Models such as ApiDoc, ApiDocAction, ApiDocInfo, etc. represent the structure of the documentation data.
– Exception & Utility Modules:
• Packages such as com.apidoc.exception and com.apidoc.utis (including the utils subpackages) handle error management, class scanning, JSON conversion, and string/hashing utilities.
b. Documentation Generation Service:
– The GeneratorApiDoc class (in com.apidoc) is the central service that scans annotated Java packages.
– It processes annotations from controller classes and bean definitions, gathers meta-data, optionally connects to a database to retrieve table information (via com.apidoc.utis.DatabaseMetaDataUtil), and assembles the JSON documentation.
c. Demo / Application Layer:
– There is a demo Spring Boot application under com.demo that shows how to integrate the tool.
– Controllers like ApiDocController, UserController, etc., in the demo package demonstrate how the generated JSON documentation is exposed via REST APIs.
d. Frontend / Presentation Layer:
– The static front-end files (Angular-based, compiled into HTML, CSS, JS, located under src/main/resources/static/apidoc) are responsible for rendering the documentation UI.
– These static files consume the JSON output from the Documentation Generation Service and render a user-friendly API documentation interface.
e. Database Connection (Optional):
– Although the primary function is annotation scanning, there is support for connecting to a database (via configuration in application.properties and scripts under src/main/resources/db) to extract schema/table details for additional documentation accuracy.
Relationships, Data Flow, and Interactions
– The API Annotation Module is “consumed” by the Documentation Generation Service (GeneratorApiDoc) which scans the Java packages.
– The Generation Service transforms the collected metadata into standard JSON objects based on the models in the API Model Module.
– The demo’s REST Controllers (e.g., ApiDocController) act as the API gateway to serve the generated documentation JSON.
– The static Angular-based frontend requests the JSON from these endpoints, parses it, and produces the interactive documentation interface.
– Optionally, if using database metadata for tables, the Documentation Generation Service interfaces with the Database MetaData Util to incorporate database schema information into the final document.
Architectural Patterns and Design Principles
– Modular Design: The separation between annotation scanning, model formation, web service interface, and front-end rendering makes for a clean, modular architecture.
– Frontend-Backend Separation: The project demonstrates a clear separation of concerns with a Spring Boot backend and an Angular (static) frontend.
– Annotation-Driven Development: Using Java annotations enables metadata to drive documentation generation dynamically.
– Utility/Helper Pattern: The use of utility classes (in utis and utis/utils) is critical for common tasks like class scanning and JSON conversion.
Final Checklist
– Ensure every component is labeled with its name and a brief description.
– Capture the modular design by breaking the system into as many meaningful components as possible, each depicting its role in the overall workflow.