微服务集成smart-doc和Torna

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

            <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>2.4.6</version>
                <configuration>
                    <!--指定生成文档的使用的配置文件-->
                    <configFile>${basedir}/src/main/resources/smart-doc.json</configFile>
                    <!--指定项目名称-->
                    <projectName>API</projectName>
                    <!--指定扫描某目录的文件-->
<!--                    <includes>-->
<!--                        <include>com.zhulin:.*</include>-->
<!--                    </includes>-->
                    <excludes>
                        <!--格式为：groupId:artifactId;参考如下-->
                        <!--也可以支持正则式如：com.alibaba:.* -->
                        <exclude>com.alibaba.*:.*</exclude>
                        <exclude>io.netty:.*</exclude>
                        <exclude>org.springframework.cloud:.*</exclude>
                    </excludes>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                        <phase>install</phase>
                        <goals>
                            <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

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

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

<includes>
    <include>com.zhulin:.*</include>
</includes>

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

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

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

<excludes>
      <!--格式为：groupId:artifactId;参考如下-->
       <!--也可以支持正则式如：com.alibaba:.* -->
       <exclude>com.alibaba.*:.*</exclude>
       <exclude>io.netty:.*</exclude>
       <exclude>org.springframework.cloud:.*</exclude>
</excludes>

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

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

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

 <execution>
       <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
       <phase>install</phase>
       <goals>
            <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
            <goal>html</goal>
            </goals>
</execution>

这里可知当maven插件去执行install时，smart-doc会进行启动执行<phase>install</phase>中可以填写别的值，如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可看到我们的接口信息