How tongchengopensource/smart-doc-maven-plugin works
Project Type and Purpose
• This is an open-source Maven plugin (“smart-doc-maven-plugin”) that hooks into the Maven build lifecycle to automatically generate API documentation from Java source code.
• It does not provide a UI; instead, it acts as a bridge between your Java project and the Smart-Doc core engine (and optionally external services such as Torna).
High-Level File-Structure Analysis
• pom.xml – declares this module as a Maven plugin and its dependencies.
• src/main/java/com/ly/doc/plugin
• chain – a Chain of Responsibility implementation for filtering artifacts on the classpath (e.g., by groupId, artifactId, prefixes, etc.).
• constant – global and Mojo-specific configuration keys.
• mojo – one Mojo class per goal (html, markdown, adoc, openapi, torna-rest, etc.), all extending BaseDocsGeneratorMojo.
• util – helper classes for class loading, file operations, reading plugin configurations, etc.
• src/main/resources – default.json (fallback defaults) and smart-doc.json (user-supplied configuration).
README Insights
• The plugin reads smart-doc.json (or defaults), analyzes the Maven project’s dependency tree, applies include/exclude filters, then invokes Smart-Doc’s code-analysis engine.
• It supports multiple “goals” (Mojo classes): html, markdown, adoc, postman, openapi, word, jmeter, RPC variants, and Torna push.
• Emphasizes zero-intrusion: no test harness needed, runs as part of “mvn compile” (or via IDE).
Main Components
a. Maven Core
• Lifecycle Phases & Plugin API
b. Smart-Doc Maven Plugin
• Mojo Layer – one class per goal (e.g., HtmlMojo, MarkdownMojo, OpenApiMojo, TornaRestMojo, etc.)
• Config Reader – reads smart-doc.json or default.json
• Dependency Analyzer – traverses the project’s dependency graph via Maven Project API
• FilterChain – applies chain-of-responsibility filters (CommonArtifactFilterChain, GroupIdFilterChain, etc.)
• Smart-Doc Engine Invocation – hands off filtered classes/sources to the Smart-Doc core library
• Format Renderers – built‐in Smart-Doc format modules (HTML, Markdown, ADOC, OpenAPI JSON, Postman, Word, JMeter)
• TornaClient – when the Torna goal runs, pushes generated docs to the external Torna REST API
c. Resources
• smart-doc.json (user config)
• default.json (plugin defaults)
d. Inputs & Outputs
• Input: Java source code + annotations + smart-doc.json
• Output: documentation artifacts (files on disk) and/or HTTP calls to Torna
Relationships & Data Flow
1. Maven invokes the selected Mojo during the build phase (e.g., compile)
2. Mojo loads configuration (smart-doc.json or default.json)
3. Mojo uses the Maven Project API to collect project classes and dependencies
4. Dependency Analyzer feeds artifacts through the FilterChain
5. FilterChain outputs a set of source‐code locations to process
6. Mojo calls the Smart-Doc core engine, passing in source locations and config
7. Smart-Doc core analyzes code, builds an API model
8. Format Renderer module generates files (HTML/MD/ADOC/OpenAPI/Word, etc.) into outPath
9. If Torna goal: TornaClient issues REST calls to push JSON payloads to the Torna server
Architectural Patterns & Principles
• Plugin/Mojo extension point pattern (Maven Plugin API)
• Chain of Responsibility for flexible artifact filtering
• Separation of concerns: config reading, filtering, engine invocation, rendering, external integration
• Convention-over-configuration: default.json vs. optional smart-doc.json
Technologies & Frameworks
• Java 1.8+
• Maven Plugin API
• Smart-Doc Core Library (embedded as a dependency)
• Jackson/Gson (for parsing smart-doc.json)
• HTTP client (for Torna REST)
• Standard I/O and ClassLoader utilities
Essential Elements to Capture
• Plugin API → Mojo invocation
• Config loading (default.json vs. smart-doc.json)
• DependencyAnalyzer + FilterChain (chain‐of‐responsibility)
• Engine invocation and format renderers
• Torna integration path (HTTP client)
• Inputs (source + annotations) and outputs (files + REST calls)