干掉 swagger 接口文档自动生成神器smart-doc+torna

接口文档自动生成神器

当下其他接口文档工具存在的痛点？

1. 需要纯手工一个个编辑，极其繁琐

1. 需要依赖一些额外的注解，编写繁琐，让代码变得臃肿（比如swagger）

1. 需要一定学习成本，如某个特殊注解

1. 如果接口更新，无法自动感知刷新

1. 接口文档信息存储在第三方平台上不安全

1. 不免费（对接口数量/团队人数有限制）

smart-doc+torna 优势

1. 不存在上述缺点

1. 平台开源免费

smart-doc+torna介绍

理念：代码即文档

smart-doc（接口文档插件） + Torna （接口管理平台）组成行业领先的文档生成和管理解决方案，使用smart-doc无侵入完成JAVA源代码分析和提取注释生成API文档，自动将文档推送到Torna企业级接口文档管理平台。

直接上手

1. 下载torna https://gitee.com/durcframework/torna/releases/tag/v1.27.0

1. 启动torna ：start torna.jar

1. 
2. 添加pom依赖

<!--            接口文档插件配置开始-->

<plugin>

    <groupId>com.github.shalousun</groupId>

    <artifactId>smart-doc-maven-plugin</artifactId>

    <version>2.2.8</version>

    <configuration>

        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->

        <configFile>./src/main/resources/smart-doc.json</configFile>

        <!--指定项目名称-->

        <projectName>测试</projectName>

        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->

        <excludes>

            <!--格式为：groupId:artifactId;参考如下-->

            <!--1.0.7版本开始你还可以用正则匹配排除,如：poi.* -->

            <exclude>com.alibaba:fastjson</exclude>

        </excludes>

        <!--自1.0.8版本开始，插件提供includes支持-->

        <!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->

        <includes>

            <!--格式为：groupId:artifactId;参考如下-->

            <include>com.alibaba:fastjson</include>

        </includes>

    </configuration>

    <executions>

        <execution>

            <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->

            <phase>compile</phase>

            <goals>

                <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->

                <goal>torna-rest</goal>

            </goals>

        </execution>

    </executions>

</plugin>

<!--            接口文档插件配置结束-->

1. 创建一个项目，并且复制token

1. 在resource目录下添加配置文件，把appToken替换成上图中的：

[smart-doc.json]

1. 编写接口

1. 编写正常接口注释和字段注释即可，无需额外的注解

生成文档：点击maven ->plugins> smart-doc

结果展示