# cvs6/api-doc architecture

> Architecture diagram of the GitHub repository cvs6/api-doc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cvs6/api-doc
- Repository: https://github.com/cvs6/api-doc

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        AngularFrontend["Angular Frontend\n(Static files)"]
    end

    %% Backend Service Layer
    subgraph "Backend Service Layer"
        DemoApplication["Demo Application (Spring Boot)"]
        DemoControllers["REST Controllers\n(ApiDocController, etc.)"]
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        APIAnnotation["API Annotation Module\n(Java annotations for API)"]
        APIModel["API Model/Bean Module\n(Documentation data models)"]
        ExceptionModule["Exception Module\n(Error management)"]
        UtilityModule["Utility Modules\n(Class scanning, JSON conversion, etc.)"]
        GeneratorService["Documentation Generation Service\n(GeneratorApiDoc)"]
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        DbMetadataUtil["Database Metadata Util\n(Fetch DB schema)"]
        DbScripts["Database Scripts"]
    end

    %% Relationships / Data Flow
    APIAnnotation -->|"scansAnnotations"| GeneratorService
    APIModel -->|"providesModel"| GeneratorService
    ExceptionModule -->|"handlesErrors"| GeneratorService
    UtilityModule -->|"providesUtilities"| GeneratorService

    GeneratorService -->|"generatesJSON"| DemoControllers
    DemoApplication -->|"hostsServices"| DemoControllers
    DemoControllers -->|"servesDocTo"| AngularFrontend

    GeneratorService -->|"fetchesDBMetadata"| DbMetadataUtil
    DbScripts -->|"providesDBSchema"| DbMetadataUtil

    %% Click Events
    click APIAnnotation "https://github.com/cvs6/api-doc/tree/master/src/main/java/com/apidoc/annotation"
    click APIModel "https://github.com/cvs6/api-doc/tree/master/src/main/java/com/apidoc/bean"
    click ExceptionModule "https://github.com/cvs6/api-doc/tree/master/src/main/java/com/apidoc/exception"
    click UtilityModule "https://github.com/cvs6/api-doc/tree/master/src/main/java/com/apidoc/utis"
    click GeneratorService "https://github.com/cvs6/api-doc/blob/master/src/main/java/com/apidoc/GeneratorApiDoc.java"
    click DemoApplication "https://github.com/cvs6/api-doc/blob/master/src/main/java/com/demo/ApidocApplication.java"
    click DemoControllers "https://github.com/cvs6/api-doc/tree/master/src/main/java/com/demo/web"
    click AngularFrontend "https://github.com/cvs6/api-doc/tree/master/src/main/resources/static/apidoc"
    click DbMetadataUtil "https://github.com/cvs6/api-doc/blob/master/src/main/java/com/apidoc/utis/DatabaseMetaDataUtil.java"
    click DbScripts "https://github.com/cvs6/api-doc/tree/master/src/main/resources/db"

    %% Styles
    class AngularFrontend frontend
    class DemoApplication,DemoControllers backend
    class APIAnnotation,APIModel,ExceptionModule,UtilityModule,GeneratorService core
    class DbMetadataUtil,DbScripts infra

    classDef frontend fill:#FFDDC1,stroke:#8B4513,stroke-width:2px
    classDef backend fill:#C1FFD7,stroke:#008080,stroke-width:2px
    classDef core fill:#C1D4FF,stroke:#00008B,stroke-width:2px
    classDef infra fill:#FFC1C1,stroke:#8B0000,stroke-width:2px
```
