Doc Analyzer

Doc Analyzer（文档分析器）

当用户需要自动生成 API 文档时使用。分析 Spring MVC Controller 中的 handler 方法，提取 URL、HTTP 方法、请求/响应结构、Javadoc 注释等信息，输出为结构化文档。

前置条件

确保用户项目的 pom.xml 包含 Allison1875 Maven 插件配置：

<plugin>
    <groupId>com.spldeolin.allison1875</groupId>
    <artifactId>allison1875-maven-plugin</artifactId>
    <version>${allison1875.version}</version>
    <configuration>
        <common>
            <basePackage>用户项目的根包</basePackage>
            <author>作者名</author>
        </common>
        <docAnalyzer>
            <!-- 文档输出目标：MARKDOWN, YAPI, SHOWDOC, DSL -->
            <flushTo>MARKDOWN</flushTo>
            <!-- 其他配置见下方说明 -->
        </docAnalyzer>
    </configuration>
</plugin>

执行步骤

第一步：配置文档输出目标

在 pom.xml 的 <docAnalyzer> 中配置：

基础配置：

输出到 Markdown：

输出到 YApi：

输出到 Showdoc：

输出到 DSL：

第二步：执行 Maven 命令

mvn allison1875:doc-analyzer

输出结果

根据配置的 flushTo 输出：

1. MARKDOWN：在 markdownDir 目录生成 Markdown 格式的 API 文档
2. YAPI：同步 API 文档到 YApi 平台
3. SHOWDOC：同步 API 文档到 Showdoc 平台
4. DSL：在 dslDir 目录生成 DSL 格式文件

文档内容

分析并输出的信息包括：

• 基本信息：分类、描述、是否过时、作者、源码位置
• URL 信息：HTTP 方法、URL 路径
• Path 参数：路径变量
• Query 参数：查询字符串参数
• Request Body：请求体 JSON Schema
• Response Body：响应体 JSON Schema

配置示例

输出到本地 Markdown：

<docAnalyzer>
    <flushTo>MARKDOWN</flushTo>
    <markdownDir>docs/api</markdownDir>
    <singleEndpointPerMarkdown>true</singleEndpointPerMarkdown>
    <enableCurl>true</enableCurl>
    <enableResponseBodySample>true</enableResponseBodySample>
</docAnalyzer>

同步到 YApi：

<docAnalyzer>
    <flushTo>YAPI</flushTo>
    <yapiUrl>http://yapi.example.com</yapiUrl>
    <yapiToken>your-project-token</yapiToken>
</docAnalyzer>

只分析特定 Controller：

<docAnalyzer>
    <flushTo>MARKDOWN</flushTo>
    <mvcHandlerQualifierWildcards>
        <param>com.example.controller.UserController.*</param>
        <param>com.example.controller.OrderController.create*</param>
    </mvcHandlerQualifierWildcards>
</docAnalyzer>

故障排查

Converted and distributed by TomeVault — claim your Tome and manage your conversions.