ToB企服应用市场:ToB评测及商务社交产业平台

标题: 零侵入！试试这款Api接口文档生成器！ [打印本页]
作者: 十念    时间: 2024-4-17 22:28
标题: 零侵入！试试这款Api接口文档生成器！
大家好，我是 Java陈序员。
作为一名合格的程序员，不仅代码要写好，而且文档要写好。
虽然目前有成熟的框架可以快速生成接口文档，如大名鼎鼎的 Swagger.但是 Swagger 需要编写大量的注解来辅助生成文档，侵入了业务代码。不符合高内聚、低耦合的编程规范！
今天，给大家介绍一款零侵入的 Api 接口文档生成工具！
关注微信公众号：【Java陈序员】，获取开源项目分享、AI副业分享、超200本经典计算机电子书籍等。
项目介绍

smart-doc 是一款同时支持 JAVA REST API 和 Apache Dubbo RPC 接口文档生成的工具。完全基于注释生成文档，做到零侵入。
smart-doc 最大的优点就在于零侵入，不采用任何注解侵入到业务代码中。
只需要按照 java-doc 标准编写注释，smart-doc 就能帮你生成一个简易明了的文档。
smart-doc 生成的文档支持 Markdown、Postman Collection2.0+、HTML5、OpenAPI 3.0+.

此外，smart-doc 还支持自动推送文档到 Torna 企业级接口文档管理平台。
快速开始

1、新建 JSON 配置文件
在项目启动类所在模块的 resources 目录下创建 smart-doc.json 文件：
  1. {
  2.     "outPath": "/path/to/userdir"
  3. }
复制代码
outPath 指定文档输出的目录位置，也可以使用相对路径, 如: ./src/main/resources/static/doc
2、引入 Maven 插件依赖
  1. <plugin>
  2.     <groupId>com.ly.smart-doc</groupId>
  3.     <artifactId>smart-doc-maven-plugin</artifactId>
  4.     <version>[最新版本]</version>
  5.     <configuration>
  6.         <configFile>./src/main/resources/smart-doc.json</configFile>  
  7.         <projectName>${project.description}</projectName>  
  8.         <includes>  
  9.             
  10.             <include>com.baomidou:mybatis-plus-extension</include>
  11.             
  12.             <include>com.baomidou:mybatis-plus-core</include>
  13.             
  14.             <include>org.springframework.data:spring-data-commons</include>            
  15.         </includes>
  16.     </configuration>
  17.     <executions>
  18.         <execution>
  19.             
  20.             <phase>compile</phase>
  21.             <goals>
  22.                
  23.                 <goal>html</goal>
  24.             </goals>
  25.         </execution>
  26.     </executions>
  27. </plugin>
复制代码
如果是 Gradle 项目，同样的也需要引入插件：
  1. plugins {
  2.   id "com.ly.smart-doc" version "[最新版本]"
  3. }
复制代码
Gradle 项目完整配置可参考：
  1. https://smart-doc-group.github.io/#/zh-cn/plugins/gradle
复制代码
3、使用
在 IDEA 中直接使用 Maven 插件目录下的 smart-doc 模块

或者使用如下命令输出接口文档：
  1. mvn -Dfile.encoding=UTF-8 smart-doc:html
  2. mvn -Dfile.encoding=UTF-8 smart-doc:markdown
  3. mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest
复制代码

总结

不管是新项目，还是老项目，smart-doc 都完美适用。对于新项目不需要再引入其他框架和编写代码；老项目只要完善 java-doc 标准的注释，就可以快速生成接口文档，完全不影响到业务代码！
下次如果要编写接口接口文档，可以试试使用 smart-doc 一键生成~
当然了，smart-doc 也存在缺点，就是文档不是在线的，不利于分享！
针对于这一点，也有对应的解决方案，就是与企业级别的接口文档管理系统 Torna 结合。
最后，贴上项目地址：
  1. https://github.com/TongchengOpenSource/smart-doc
复制代码
最后

推荐的开源项目已经收录到 GitHub 项目，欢迎 Star：
  1. https://github.com/chenyl8848/great-open-source-project
复制代码
或者访问网站，进行在线浏览：
  1. https://chencoding.top:8090/#/
复制代码
大家的点赞、收藏和评论都是对作者的支持，如文章对你有帮助还请点赞转发支持下，谢谢！

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！



欢迎光临 ToB企服应用市场:ToB评测及商务社交产业平台 (https://dis.qidao123.com/) Powered by Discuz! X3.4