Java 零注解文档生成工具—smart-doc,看完有替换swagger的冲动

执笔记忆的空白 2019-11-20 14:53:08 ⋅ 116 阅读

Tips:喜欢的话可以关注小萌哦~~~

今天小萌给大家推荐的一个开源Java Restful API 文档生成工具,一加【oneplus】、iflytek都在用。所以,自然差不了。

官方简介

smart-doc 是一个 java restful api 文档生成工具,smart-doc 颠覆了传统类似 swagger 这种大量采用注解侵入来生成文档的实现方法。smart-doc 完全基于接口源码分析来生成接口文档,完全做到零注解侵入,你只需要按照java标准注释的写,smart-doc 就能帮你生成一个简易明了的 Markdown、Html、AsciiDoc 文档。

如果你已经厌倦了 swagger 等文档工具的无数注解和强侵入污染,smart-doc是不错的选择!

最新版本

smart-doc 1.7.7

  • 修改timestamp类型字段创建json示例错误bug。

  • fix #I1545A 单接口多路径bug。

  • 修改部分url生成部署空格问题。

  • 优化对java.util.concurrent.ConcurrentMap的解析。

开源地址

https://gitee.com/sunyurepository/smart-doc

快速入门

1、Getting started

https://gitee.com/sunyurepository/api-doc-test.git

你可以启动这个Spring Boot的项目,然后访问http://localhost:8080/doc/api.html来浏览smart-doc生成的接口文档。

2、Dependency

<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc</artifactId>
<version>1.7.7</version>
<scope>test</scope>
</dependency>

3、Create a unit test

通过运行一个单元测试来让Smart-doc为你生成一个简洁明了的api文档。

public class ApiDocTest {

/**
* 包括设置请求头,缺失注释的字段批量在文档生成期使用定义好的注释
*/

@Test
public void testBuilderControllersApi()
{
ApiConfig config = new ApiConfig();
config.setServerUrl("http://localhost:8080");
//true会严格要求注释,推荐设置true
config.setStrict(true);
//true会将文档合并导出到一个markdown
config.setAllInOne(false);
//生成html时加密文档名不暴露controller的名称
config.setMd5EncryptedHtmlName(true);

//指定文档输出路径
//@since 1.7 版本开始,选择生成静态html doc文档可使用该路径:DocGlobalConstants.HTML_DOC_OUT_PATH;
config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);
// @since 1.2,如果不配置该选项,则默认匹配全部的controller,
// 如果需要配置有多个controller可以使用逗号隔开
config.setPackageFilters("com.power.doc.controller");
//不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
config.setSourceCodePaths(
//自1.7.0版本开始,在此处可以不设置本地代码路径,单独添加外部代码路径即可
// SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java"),
SourceCodePath.path().setDesc("加载项目外代码").setPath("E:\\ApplicationPower\\ApplicationPower\\Common-util\\src\\main\\java")
);
//since 1.7.5
//如果该选项的值为false,则smart-doc生成allInOne.md文件的名称会自动添加版本号
config.setCoverOld(true);
//since 1.7.5
//设置项目名(非必须),如果不设置会导致在使用一些自动添加标题序号的工具显示的序号不正常
config.setProjectName("抢购系统");
//设置请求头,如果没有请求头,可以不用设置
config.setRequestHeaders(
ApiReqHeader.header().setName("access_token").setType("string").setDesc("Basic auth credentials"),
ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
);
//对于外部jar的类,编译后注释会被擦除,无法获取注释,但是如果量比较多请使用setSourcePaths来加载外部代码
//如果有这种场景,则自己添加字段和注释,api-doc后期遇到同名字段则直接给相应字段加注释
config.setCustomResponseFields(
CustomRespField.field().setName("success").setDesc("成功返回true,失败返回false"),
CustomRespField.field().setName("message").setDesc("接口响应信息"),
CustomRespField.field().setName("data").setDesc("接口响应数据"),
CustomRespField.field().setName("code").setValue("00000").setDesc("响应代码")
);

//设置项目错误码列表,设置自动生成错误列表,
List<ApiErrorCode> errorCodeList = new ArrayList<>();
for (ErrorCodeEnum codeEnum : ErrorCodeEnum.values()) {
ApiErrorCode errorCode = new ApiErrorCode();
errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getDesc());
errorCodeList.add(errorCode);
}
//如果没需要可以不设置
config.setErrorCodes(errorCodeList);

//非必须只有当setAllInOne设置为true时文档变更记录才生效,https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O
config.setRevisionLogs(
RevisionLog.getLog().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("测试").setStatus("创建").setVersion("V1.0"),
RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("测试2").setStatus("修改").setVersion("V2.0")
);

//since 1.7.5
//文档添加数据字典
config.setDataDictionaries(
ApiDataDictionary.dict().setTitle("订单状态").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc"),
ApiDataDictionary.dict().setTitle("订单状态1").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc")
);


long start = System.currentTimeMillis();
ApiDocBuilder.builderControllersApi(config);

//@since 1.7+版本开始,smart-doc支持生成带书签的html文档,html文档可选择下面额方式
//HtmlApiDocBuilder.builderControllersApi(config);
//@since 1.7+版本开始,smart-doc支撑生成AsciiDoc文档,你可以把AsciiDoc转成HTML5的格式。
//@see https://gitee.com/sunyurepository/api-doc-test
//AdocDocBuilder.builderControllersApi(config);

long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
}

4、接口头部效果图


Java 零注解文档生成工具—smart-doc,看完有替换swagger的冲动

5、请求参数示例效果图


Java 零注解文档生成工具—smart-doc,看完有替换swagger的冲动

6、响应参数示例效果图


Java 零注解文档生成工具—smart-doc,看完有替换swagger的冲动

给使用者的建议

  • smart-doc虽然可以关闭注解检测,好的规范更容易让项目变得更容易维护* smart-doc的出发的目标不是仅仅为书写接口的开发人员自己测试接口服务的,而是希望导出的文档能够用极少的变更就能做接口服务对接文档。* smart-doc主要目的是为了减少接口文档书写和造测试模拟数据* smart-doc拉取了大量的开源项目做了源码解析测试,开发过程中也做了很多实际场景的思考,工具开源的目的不是做着玩,而是想帮助大家解决问题。

评价

看过示例之后是不是想要有替换swagger的冲动?别着急,swagger虽然耦合很严重,但是这个也直接避免了一些懒惰的开发人员改接口不改注释的习惯。




全部评论: 0

    我有话说:

    smart-doc 2.0.0 重磅发布,Java 注解 API 文档生成工具

    smart-doc是一款同时支持java restful api和apache dubbo rpc接口文档生成工具smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档

    Swagger接口文档工具:Knife4j 2.0.7 发布,细节优化

    Knife4j前身是swagger-bootstrap-ui,是一个为Swagger接口文档赋能工具 文档:https://doc.xiaominfo.com 效果(旧版):http

    swagger-admin v1.3.5 已经发布,Swagger 文档管理后台

    swagger-admin v1.3.5 已经发布,这是一个Swagger文档管理后台,可统一管理多个项目Swagger文档,只需要一个Java8环境,下载后即可运行使用。 支持导入json,非

    Google发布Java 核心工具库——Guava 28.0

    Guava是一种基于开源Java库,其中包含谷歌正在由他们很多项目使用很多核心库。这个库是为了方便编码,并减少编码错误。这个库提供用于集合,缓存,支持原语,并发性,常见注解,字符串处理,I/O和

    精品推荐:Javascript 将 HTML 页面生成 PDF 并下载

    最近碰到个需求,需要把当前页面生成 pdf并下载,需要可以看看哦~~~

    最全Mac工具

      MacTool Mac 开源免费工具汇总, 只罗列开源好用。更全列表请参考awesome-mac 必备 Homebrew - 体验通过命令行安装 Mac 软件工具(大部分是

    工具集002

      文件对比 https://www.diffchecker.com/excel-diff 快速找出类似文件不同之处。  

    「开源资讯」Guava 28.2 发布,Google Java 核心工具

    前言 Guava 28.2 发布了,Guava 是 Google 一个开源项目,包含许多 Google 核心 Java 常用库,如:集合 [collections] 、缓存 [caching

    工具集001

      1.  Google项目管理工具 Tables   2. 终端 taskwarrior --- TODO List Taskwarrior is

    「尝鲜」SpringBoot 快速整合Swagger 3.0

    第一步:Maven引入Swagger3.0 starter依赖 Maven项目中引入springfox-boot-starter依赖: <dependency> <

    Knife4j 2.0.8 发布,轻量级微服务聚合文档中间件诞生

    Knife4j前身是swagger-bootstrap-ui,是一个为Swagger接口文档赋能工具 文档:https://xiaoym.gitee.io/knife4j/ 效果(旧版):http

    「轻阅读」最近程序员圈刷屏支付宝架构,分享给大家

    支付宝架构到底多牛逼!还没我就跪了

    蚂蚁金服 Java RPC 开源框架—SOFARPC

    SOFARPC 是一个高可扩展性、高性能、生产 Java RPC 框架。

    前端实战篇:JavaScript 反调试技巧简单应用(上)

    最近作者了一些关于JavaScript反调试帖子,今天给大家整理一下希望帮助。

    「轻阅读」图解 Java 线程生命周期

    Java 线程生命周期中都包含哪些状态?生命周期中各个状态都是什么含义?

    Google 宣布正式开源 Jib ,帮助 Java 应用快速容器化

    Google 本周宣布开源一款新 Java 工具 Jib ,旨在让开发者使用他们熟悉工具更轻松地将 Java 应用程序容器化。

    微信开发神器全能微信Java开发工具包

    必须分享微信神器 weixin-java-tools

    Gradle 5.0 RC2 发布,支持 Java 11、Kotlin DSL 生产就绪

    Gradle 5.0 RC2 发布了,Gradle 是一个基于 Apache Ant 和 Apache Maven 概念项目自动化构建工具,支持依赖管理和多项目,类似 Maven,但比之简单轻便。

    精品推荐:一览GitHub上最受程序欢迎5大Java开源项目

    列举了GitHub上一些最流行Java项目。从Mockitos到Guava,以及 java-design-patterns等供大家学习。