Java使用smart-doc自动生成文档

作为后端开发，写接口文档一直是一个很头痛的问题，今天推荐一个开源工具smart-doc，这个工具基于java原生的注释生成api文档，无需大量的注解配合使用。

官方地址：https://gitee.com/smart-doc-team/smart-doc

转载博客：来自51CTO博客作者上官胡闹的原创作品

一、当前市面上文档工具存在的问题
下面来列举当前市场上主流文档工具的问题：

侵入性强，需要编写大量注解，代表工具如：swagger，还有一些公司自研的文档工具
强依赖性，如果项目不想使用该工具，业务代码无法编译通过。
代码解析能力弱，使用文档不齐全，主要代表为国内众多开源的相关工具。
众多基于注释分析的工具无法解析jar包里面的注释(sources jar包)，需要人工配置源码路径，无法满足DevOps构建场景。
无法支持多模块复杂项目代码分析。

二、smart-doc如何解决上述问题
通过分析源码注释自动生成API文档，不用编写任何注解，秉承注释即文档的原则，并且提供注释强制检查。
smart-doc开发了smart-doc-maven-plugin和smart-doc-gradle-plugin插件，项目仅仅依赖插件，剔除插件无修改项目不报任何编译错误。
smart-doc在国内经过上百家企业的使用，做了很多场景的分析，解析能力很强。
smart-doc的maven和gradle插件自动分析项目依赖，自动完成对自发布jar包和第三方jar包源码的加载，不需要指定任何源码路径。
smart-doc的maven和gradle能够自动识别项目依赖，多模块maven和gradle项目都不是问题。
smart-doc文档维护比较完善，码云上的wiki有20个页面介绍各种使用方式。

三、smar-doc的不足
smart-doc并非是完美的，仍然有很多不足。

界面支持不完善，没有发送请求的页面，无法满足小团队自测。
一些使用场景支持不完善，存在一些bug。
开源团队人员少，功能实现慢。

四、spring boot集成smart-doc生成文档。
上面说了关于一起其它工具的问题，也介绍了smart-doc的优缺点，下面进入正题，如何快速使用smart-doc生成文档。

4.1 添加插件

在spring boot项目pom中添加smart-doc的maven插件

 <plugin><groupId>com.github.shalousun</groupId><artifactId>smart-doc-maven-plugin</artifactId><version>[最新版本]</version><configuration><!--指定生成文档使用的配置文件--><configFile>./src/main/resources/smart-doc.json</configFile></configuration><executions><execution><!--不需要在编译项目时自动生成文档可注释phase--><phase>compile</phase><goals><goal>html</goal></goals></execution></executions>
</plugin>

4.2 添加smart-doc.json配置文件

{"serverUrl": "http://127.0.0.1",//服务器地址"isStrict": false,//是否用严格模式，严格模式强制检查注释"allInOne": true,//所有接口文档合并生成到一个文档"outPath": "src/main/resources/static/doc",//文档的输出路径"projectName": "smart-doc"//指定项目名称，用于显示在文档中
}

上面的几行配置中，实际上只有outPath是必须要的，其他都是非必须。相比其它工具，smart-doc配置简单又不会影响到项目。详细配置请参考smart-doc插件使用

4.3 编写controller接口

@RestController
@RequestMapping("/user")
public class UserController {/*** 添加用户* @param user* @return*/@PostMapping("/add")public User addUser(@RequestBody User user){return user;}
}

实体类：

public class User {/*** 用户名*/private String userName;/*** 昵称*/private String nickName;/*** 用户地址*/private String userAddress;/*** 用户年龄*/private int userAge;/*** 手机号*/private String phone;/*** 创建时间*/private Long createTime;/*** ipv6*/private String ipv6;/*** 固定电话*/private String telephone;//省略get set
}

4.4 运行插件生成文档

生成文档：

当前最新的smart-doc结合插件后，已经做到了非常易于使用，只需要引入插件和根据自己需求填充相关的配置即可，非常的轻量级。

Java使用smart-doc自动生成文档相关推荐

java动态生成sdk_android、java制作sdk以及自动生成文档
最近一直在做android开发,昨天经理让我写个接口SDK做个接口文档,以便后面的开发. 这让我很焦灼,SDK怎么做?要是只有敲代码还好.可是那个接口文档!!!文档这东西最讨厌了,头都大了后来查了下 ...
java如何写安卓接口文档_android、java制作sdk以及自动生成文档
最近一直在做android开发,昨天经理让我写个接口SDK做个接口文档,以便后面的开发. 这让我很焦灼,SDK怎么做?要是只有敲代码还好.可是那个接口文档!!!文档这东西最讨厌了,头都大了后来查了下 ...
spring boot rest接口自动生成文档（包含swagger）
spring boot rest接口自动生成文档(包含swagger) 写接口免不了写接口文档,但是当文档与代码分开独立演进的时候,会发生很多不同步的问题. 接口描述与代码同 ...
java前端目录_[Java教程]前端那点事儿——Tocify自动生成文档目录
[Java教程]前端那点事儿--Tocify自动生成文档目录 0 2016-06-29 22:00:07 今天偶然间看到文档服务器有一个动态目录功能,点击目录能跳转到指定的位置:窗口滑动也能自动更新目 ...
java接口废弃注释_Spring Boot如何让Web API自动生成文档，并解决swagger-annotations的API注解description属性废弃的问题...
前后端分离的系统架构中,前端开发人员需要查看后端WEB API的文档来进行开发.采用后端API文档自动生成的方式,可以大幅提高开发效率.swagger是一个被广泛使用的文档自动生成工具,可以与多种编程 ...
spring boot rest接口自动生成文档（包含swagger）--gradle 下的配置
之前写过一篇文章:spring boot rest接口自动生成文档(包含swagger),这个使用的是maven作为依赖管理工具,现在,让我们体验一下gradle在spring boot项目中如何配置 ...
Objective-C自动生成文档工具:appledoc
作者 iOS_小松哥关注 2016.12.13 15:47* 字数 919 阅读 727评论 10喜欢 35 由于最近琐事比较多,所以好久没有写文章了.今天我们聊一聊Objective-C自动生成文 ...
Objective-C 自动生成文档工具:appledoc
来源:iOS_小松哥 www.jianshu.com/p/fd4d8d6b6177 如有好文章投稿,请点击 → 这里了解详情由于最近琐事比较多,所以好久没有写文章了.今天我们聊一聊Objective ...
MQL5 代码自动生成文档
1. 简介大多数 Java 代码编写者熟悉可通过 JavaDocs 创建的自动生成文档.其思路是以一种半结构化的方式向代码添加注释,然后可以将这些注释提取到易于导航的帮助文件. C++ 世界也有若干 ...

Java使用smart-doc自动生成文档

Java使用smart-doc自动生成文档相关推荐

最新文章

热门文章