微服务api和通用api（微服务接口文档一站搞定）

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

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

下载地址： https://gitee.com/durcframework/torna/releases

解压文件：如图所示。

修改配置：以下数据库配置项修改为各位读者自己的配置。

# Server port server.port=7700 # MySQL host mysql.host=${MYSQL_HOST:localhost:3306} # Schema name mysql.schema=${MYSQL_SCHEMA:torna} # Make sure the account can run CREATE/ALTER sql. mysql.username=${MYSQL_USERNAME:root} mysql.password=${MYSQL_PASSWORD:root}

https://gitee.com/durcframework/torna/blob/master/mysql.sql

执行sh startup.sh启动（Windows执行startup.bat）

用户名：admin，密码：123456

登录成功后，直接点击创建空间

进入商品中心，创建商品主数据和商品定价2个项目。

进入商品主数据，创建大件商品主数据模块。

这里的OpenAPI将用于管理和保存在线接口文档。

smart-doc从2018年的开源后的持续发展中，我们收到了很多的用户的需求， 很多企业用户非常需要一个好用的集中化API管理平台。在过去Yapi可以说是国内开源市场长用户量比较多的开源产品。但是在smart-doc作者长期的观察中，Yapi有诸多的问题。因此2020年，我们一直在社区寻找合适的开源合作者来重心打造一款企业级的API文档管理平台。很幸运的在开源社区找到了@tanghc。 @tanghc是一个有多个开源项目的作者，而且非常热衷于开源。我们向 @tanghc 描述了做API管理平台的项目和理念。最终我们达成了做torna的共识。为开源社区提供一个好的文档生成和管理的解决方案。当然未来我们会探索出商业化的产品。 但是smart-doc和smart-doc的maven、gradle插件是免费。当前提供的torna基础功能也是免费开源给社区使用。torna商业版本主要面向企业的高级功能版本。

引入smart-doc插件。

<plugin> <groupId>com.github.shalousun</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>[最新版本]</version> <configuration> <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中--> <configFile>./src/main/resources/smart-doc.json</configFile> <!--指定项目名称--> <projectName>测试</projectName> <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉--> <excludes> <!--格式为：groupId:artifactId;参考如下--> <!--也可以支持正则式如：com.alibaba:.* --> <exclude>com.alibaba:fastjson</exclude> </excludes> <!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部源代码而不是自动加载所有，因此使用时需要注意--> <!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件--> <includes> <!--格式为：groupId:artifactId;参考如下--> <!--也可以支持正则式如：com.alibaba:.* --> <include>com.alibaba:fastjson</include> </includes> </configuration> <executions> <execution> <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉--> <phase>compile</phase> <goals> <!--smart-doc提供了html、openapi、markdown等goal，可按需配置--> <goal>html</goal> </goals> </execution> </executions> </plugin>

configFile标签中的配置项是smart-doc配置文件的地址。将以下信息放到./src/main/resources/smart-doc.json中。

{ "serverUrl": "http://127.0.0.1", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量 "isStrict": false, //是否开启严格模式 "outPath": "", //指定文档的输出路径,maven插件不需要，gradle插件必须 "packageFilters": "",//controller包过滤，多个包用英文逗号隔开 "projectName": "smart-doc",//配置自己的项目名称 "appToken": "c16931fa6590483fb7a4e85340fcbfef", //OpenAPI中对应的token，上文中有提及 "appKey": "20201216788835306945118208",//torna平台对接appKey，torna 1.11.0版本后不再需要, @since 2.0.9, "secret": "W.ZyGMOB9Q0UqujVxnfi@.I#V&tUUYZR",//torna平台secret，torna 1.11.0版本后不再需要，@since 2.0.9 "openUrl": "http://localhost:7700/api",//torna平台地址，填写自己的私有化部署地址@since 2.0.9 "debugEnvName":"测试环境", //torna测试环境 "replace": true,//推送torna时替换旧的文档 "debugEnvUrl":"http://127.0.0.1",//torna }

/** * @Author : 无双 * @Date : 3/15/22 8:50 PM * @Version : V1.0 * @Description : 商品主数据Rest接口 */ @RestController @RequestMapping("/goods") public class ProductController { /** * 保存产品信息 * * @param productInfo */ @RequestMapping("save") public void save(ProductInfo productInfo) { } /** * 修改产品信息 * * @param productInfo */ @RequestMapping("update") public void update(ProductInfo productInfo) { } }

使用smart-doc生成rest接口文档并推送到torna

torna接口平台接收到接口文档。

/** * @Author : 无双 * @Date : 3/15/22 9:07 PM * @Version : V1.0 * @Description : 产品接口 */ public interface ProductFacade { /** * 保存产品Dubbo接口 * * @param productInfo */ void save(ProductInfo productInfo); /** * 更新产品Dubbo接口 * * @param productInfo */ void update(ProductInfo productInfo); } /** * @Author : 无双 * @Date : 3/15/22 9:09 PM * @Version : V1.0 * @Description : 产品接口实现类 */ @Service public class ProductServiceImpl implements ProductFacade { /** * 保存产品Dubbo接口 * * @param productInfo */ @Override public void save(ProductInfo productInfo) { } /** * 更新产品Dubbo接口 * * @param productInfo */ @Override public void update(ProductInfo productInfo) { } }

使用smart-doc生成Dubbo接口文档并推送到torna