【Java】java | smart-doc + tonar | API文档统一管理

一、说明        

        1、准备舍弃swagger了，拥抱smart-doc

        2、win10

        3、jdk8

        4、idea

二、搭建torna

1）下载zip

https://foruda.gitee.com/attach_file/1672544760054905357/torna-1.19.4.zip?token=25e02a8e2817a757a0aa47172349cc20&ts=1675345098&attname=torna-1.19.4.zip

2）也可以下载最新版

https://gitee.com/durcframework/torna/releases

3）创建数据库并导入初始化脚本

数据库： MySQL 5.6以上
库名： tonar

4）mysql脚本

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

5）启动即可

端口： 7700

账号： admin

密码： 123456

6）后台管理-创建用户

7）创造空间

8）创建项目

9）查看smart-doc的token

到此，配置完成

~~

 三、项目配置smart-doc

1）使用maven插件即可

<plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <!--<version>2.0.9</version>-->
                <version>2.6.4</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>
                        <!-- 使用了mybatis-plus的Page分页需要include所使用的源码包 -->
                        <!--<include>com.baomidou:mybatis-plus-extension</include>-->
                        <!-- 使用了mybatis-plus的IPage分页需要include mybatis-plus-core-->
                        <!--<include>com.baomidou:mybatis-plus-core</include>-->
                        <!-- 如果配置了includes的情况下， 使用了jpa的分页需要include所使用的源码包 -->
                        <include>org.springframework.data:spring-data-commons</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>

2）配置示例

3）配置smart-doc.json

{
  "outPath": "src/main/resources/static/doc",
  "serverUrl": "http://127.0.0.1",
  "isStrict": false,
  "packageFilters": "",
  "projectName": "eladmin-java",
  "appToken": "0fe821154b134ec5b52ce56315c7afe7",
  "appKey": "",
  "secret": "",
  "openUrl": "http://localhost:7700/api",
  "debugEnvName":"测试环境",
  "replace": true,
  "debugEnvUrl":"http://127.0.0.1"
}

 4）通过插件生成doc

5）推送成功示例

6）到torna刷新查看

真香~~~

7）smart-doc扩展了注解，了解一下

https://smart-doc-group.github.io/#/zh-cn/start/javadoc?id=smart-doc%e8%87%aa%e5%ae%9a%e4%b9%89%e6%b3%a8%e9%87%8atag

~~