smart-doc+torna接口文档集成

💡 接口文档解决方案，目标是让接口文档管理变得更加方便、快捷。Torna采用团队协作的方式管理和维护接口文档，将不同形式的文档纳入进来统一维护。

Torna弥补了传统文档生成工具（如swagger）的不如之处，在保持原有功能的前提下丰富并增强了一些实用的功能。

解决文档管理痛点

• 不满足swagger文档预览页面和调试页面的展现方式
• 不喜欢swagger这种侵入式注解
• 希望使用javadoc注释生成文档，并进行接口调试
• 希望把公司所有项目接口文档进行统一管理
• 希望把项目中的若干文档提供给第三方调用者查看
• 希望可以统一管理项目中的字典枚举

搭建步骤

torna搭建

• 下载最新版zip包（gitee.com/durcframewo…）
• 导入mysql数据库（gitee.com/durcframewo…）
• 打开application.properties配置文件，修改数据库连接配置
• 执行sh startup.sh启动（Windows执行startup.bat）
• 访问：http://ip:7700 登录账号：用户名：admin，密码：123456
• 后续升级无特殊说明，只需要覆盖torna.jar文件和dist文件夹，然后重启即可
• 清表

truncate table doc_info;
truncate table doc_param;
truncate table enum_info;
truncate table enum_item;
truncate table module;
truncate table module_environment;
truncate table project;
truncate table project_user;
truncate table `space` ;
truncate table space_user ;

truncate table compose_additional_page;
truncate table compose_common_param;
truncate table compose_doc;
truncate table compose_project;
truncate table constant_info;
truncate table module_config;
truncate table open_user;

truncate table prop;
truncate table system_config;
truncate table user_info;
truncate table user_message;
truncate table user_subscribe;

smart-doc搭建

• 引入插件

<!-- smart-doc插件 -->
<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.4.9</version>
    <configuration>
        <!--指定生成文档的使用的配置文件-->
        <configFile>${basedir}/src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>后台管理</projectName>
        <excludes>org.springframework.data:spring-data-commons</excludes>
    </configuration>
    <executions>
        <execution>
            <phase>package</phase>
        </execution>
    </executions>
</plugin>

• resources下新建smart-doc.json配置文件

{
  "outPath": "",
  "projectName": "后台管理",
  "packageFilters": "com.sci99.mtd.scipprmanage.controller.*",
  "openUrl": "<http://127.0.0.1:7700/api>",
  "appToken": "0fd5a7b00f0b4467830a7c52397a7f1e",
  "debugEnvName":"本地环境",
  "debugEnvUrl":"<http://127.0.0.1:5020>",
  "tornaDebug": true,
  "replace": true
}

• openUrl、appToken从torna获取

• 按照 javadoc 注释规范编写注释（smart-doc-group.github.io/#/zh-cn/sta…）
• maven命令推入torna