微服务集成smart-doc和Torna

1、父节点pom加入smart-doc插件

 
            <plugin>
                <groupId>com.github.shalousungroupId>
                <artifactId>smart-doc-maven-pluginartifactId>
                <version>2.4.6version>
                <configuration>
                    
                    <configFile>${basedir}/src/main/resources/smart-doc.jsonconfigFile>
                    
                    <projectName>APIprojectName>
                    
                    <excludes>
                        
                        
                        <exclude>com.alibaba.*:.*exclude>
                        <exclude>io.netty:.*exclude>
                        <exclude>org.springframework.cloud:.*exclude>
                    excludes>
                configuration>
                <executions>
                    <execution>
                        
                        <phase>installphase>
                        <goals>
                            
                            <goal>htmlgoal>
                        goals>
                    execution>
                executions>
            plugin>

${basedir}/src/main/resources/smart-doc.json

这里的意思是会扫描所有子项目下resources的smart-doc.json文件，所以我们在子项目中新增对应的smart-doc.json即可

    com.zhulin:.*

includes和下面excludes可以各选一个来处理，includes为指定扫描包下的接口

上面的意思就是只扫描com.zhulin包下的文件

采用这种方法的话建议直接扫描根目录包，如（com.zhulin:.*），不要指定扫描某个controller包，因为controller还引用了别的包的文件，由于扫描不到别的包，这样会出问题。

     
       
       com.alibaba.*:.*
       io.netty:.*
       org.springframework.cloud:.*

这里excludes是为了排除smart-doc进行扫描这里面的包，理论上我们只想smart-doc去扫描我们的自己写的项目文件,仅此而已。excludes中的设置不是固定的，是根据我们的项目引用了什么依赖来定

举个例子：当我们去执行插件命令

看到如下日志可知，smart-doc去扫描了nacos-client了，那么这不是我们期望的，那么我们在excludes中加上com.alibaba.*:.*即可消除

 
       
       install
       
           
            html
           

这里可知当maven插件去执行install时，smart-doc会进行启动执行install中可以填写别的值，如compile/package等

2、子模块添加smart-doc.json

直接放入resources目录下即可

smart-doc.json内容如下：

{
  "outPath": "target/doc",
  "projectName": "文件服务接口",
  "packageFilters": "com.zhulin.file.controller.*",
  "openUrl": "http://192.168.3.128:7700/api",
  "appToken": "2ba95a38f1094cd09a31b10b68fff06a",
  "debugEnvName":"本地环境",
  "debugEnvUrl":"http://localhost:8080/file",
  "tornaDebug": true,
  "replace": true
}

outPath代表执行插件命令后文档输出到哪个目录下
packageFilters：指定controller包目录
openUrl：采用填写torna的api访问路径  
appToken：该子模块对应torna创建的模块所产生的token
debugEnvName:环境名称，理论上可根据环境切换
debugEnvUrl：环境的具体访问前缀路径
tornaDebug和replace固定为true即可

openUrl和appToken来源于如下图：下面步骤会说明如何到此页面

部署torna推荐使用docker，可看上期文章

3、在torna新建该项目

 

 

 

 

 由上面smart-doc.json对应子模块为文件管理，那么我就起名文件管理模块

创建好后进入OpenAPI

 

 可以得到我们上面smart-doc.json需要

"openUrl": "http://192.168.3.128:7700/api",
"appToken": "880b626916d143e19e864109fb450dfd",

的2个值

 以此类推，所有的子模块服务的resources下都放入smart-doc.json，然后在torna中创建对应的模块，然后设置从OpenAPI中获取的参数进行关连。

4、执行插件命令，刷新torna查看结果

在idea中直接点击插件即可

 

 刷新torna可看到我们的接口信息