【转载】Java Restful API 文档生成工具 smart-doc
谁说生成api文档就必须要定义注解?
谁说生成接口请求和返回示例必须要在线?
用代码去探路,不断尝试更多文档交付的可能性。
如果代码有生命,为什么不换种方式和它对话!
一、背景
没有背景、就自己做自己的背景
在当今各种盛行的前后端分离、restful service开发过程中,接口文档是必不
可少的。对于前后端分离的开发中,后端开发需要将接口写好后需要告诉前端工程师接口的请求参数、响应示例等重要信息,而对于对外暴露的restful接口服务,我们提供接口也是需要具备相同的接口文档的。
但是对于后端工程师来讲,写接口文档将变成一个很大的工作量,虽然现在有类似apidoc、swagger这样的主流接口文档生成工具,但是如果实际用过,会发现这些工具不能满足实际需求,这里拿swagger为例,这个工具最大的优点能是提供在线的api文档,但是它天生就有很强的代码侵入性,要得到一个基本满足需求的api接口文档,必须在代码中使用swagger自定义的注解。这其实给开发人员增加学习成本和工作量,并且就算你使用大量的注解,有许多接口还是无法满足。因此不得不去做一次接口文档工具重新启航探索,smart-doc应允而生,用代码去探路,消除繁杂的注解,发现天下没有难写接口文档。
二、smart-doc简介
简约而不简单
smart-doc是基于java开发用于解决java web restful接口文档书写难和生成难的问题,当然api-doc也是一款零注解完全基于源代码接口定义,使用java标准注释生成接口文档的工具。并且smart-doc代码也是完全开源的。目前生成的文档格式为markdown。
三、功能特性
一个都不能少
- 零注解、零学习成本、只需要写标准java注释。
- 基于源代码接口定义自动推导
- 支持springmvc、springboot
- 目前支持javabean上定义的部分fastjson和jackson注解
- 支持javabean上基于jsr303参数检验判断参数是否为必须
- 对json请求参数的接口能够自动生成模拟json参数
- 对一些常用字段定义能够生成有效的模拟值
- 支持生成json返回值示例
- 支持从项目外部加载源代码来生成字段注释
- 一款代码注解检测工具,明眼leader都知道接口文档直接反馈出注释情况
- 支持将错误码列表和全接口生成合并到一个markdown中
四、效率成效
效率是做好工作的灵魂。——切斯特菲尔德
- 直接生成模拟请求参数,提升了团队里的前端和测试的工作效率,试想你让他们去编写json请求参数,如果你不写,鬼知道是什么样。
- 后端开发只需专注业务和写好标准注释,无需引入额外注解,无需自己编写请求参数示例和响应示例。
- 接口文档更加标准化
五、缺点
只有看到自己的不足,才能获得进步。
- 由于基于源代码分析生成文档,因此无法生成在线文档,需要结合地方markdown文档管理工具来管理。
- 由于源代码分析难度很大,针对很多代码存在潜在的大量的bug.
- 对泛型返回接口需要明确定义泛型定义,否则无法推导
六、用例
<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>api-doc</artifactId>
<version>0.5</version>
</dependency>
6.1 定义bean
/**
* @author yu 2018/8/4.
*/
public class SimpleUser {
/**
* 用户名
*/
@NotNull
private String username;
/**
* 密码
*/
private String password;
/**
* 昵称
*/
private String nickName;
/**
* 电话
*/
private String mobile;
}
6.2 定义接口
/**
* 用户信息操作接口
* @author yu 2018/8/4.
*/
@RestController
@RequestMapping("/user")
public class UserController {
/**
* 添加用户
* @param user
* @return
*/
@PostMapping("/add")
public List<SimpleUser> addUser(@RequestBody SimpleUser user){
return null;
}
}
启动文档生成
/**
* 包括设置请求头,缺失注释的字段批量在文档生成期使用定义好的注释
*/
@Test
public void testBuilderControllersApi() {
ApiConfig config = new ApiConfig();
config.setServerUrl("http://localhost:8080");
config.setStrict(true);
config.setOutPath("d:\\md");
//不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
config.setSourcePaths(
SourcePath.path().setDesc("本项目代码").setPath("src/main/java")
// SourcePath.path().setPath("E:\\Test\\Mybatis-PageHelper-master\\src\\main\\java"),
// SourcePath.path().setDesc("加载项目外代码").setPath("E:\\ApplicationPower\\ApplicationPower\\Common-util\\src\\main\\java")
);
long start = System.currentTimeMillis();
ApiDocBuilder.builderControllersApi(config);
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
生成文档
添加用户
URL: http://localhost:8080/user/add
Type: post
Content-Type: application/json; charset=utf-8
Request-parameters:
Parameter | Type | Description | Required |
---|---|---|---|
username | string | 用户名 | true |
password | string | 密码 | false |
nickName | string | 昵称 | false |
mobile | string | 电话 | false |
Request-example:
{
"username":"瑞霖.张",
"password":"xud2qc",
"nickName":"rudy.goyette",
"mobile":"15650966307"
}
Response-fields:
Field | Type | Description |
---|---|---|
username | string | 用户名 |
password | string | 密码 |
nickName | string | 昵称 |
mobile | string | 电话 |
Response-example:
[
{
"username":"浩然.阎",
"password":"dzlv56",
"nickName":"kieran.herzog",
"mobile":"17863739656"
}
]
demo地址:https://github.com/shalousun/api-doc-test
七、未来定义
期待下一次我们更好的相遇
- 修改源代码解析的众多的bug
- 收集使用者的建议,提供非json请求参数的请求示例
- 收集使用者一些新增功能建议,增加一些必须功能。
八、使用协议
尊重别人,才能让人尊敬。——笛卡尔
- 任何企业和个人不得用于申请专利
九、使用反馈
分享是一种生活的信念,明白了分享的同时,明白了存在的意义。
smart-doc的发展离不开你的支持,因为出于完全的开源免费,因此您可以基于smart-doc的源码解析核心上去做一些自定义的开发来将接口文档数据接入到一些第三方的在线api文档管理系统,例如:CrapApi,但是在请使用者能有一份开源的心态和情怀,积极反馈api-doc的核心代码使用bug和提出改善意见。<br/>
由于我个人的开发精力有限,对于是否会将smart-doc快速集成推送到第三方优秀的管理工具,短期内可能不会考虑,因此也希望使用者分享一些比较好的集成方案来供大家使用,如果方案比较符合smart-doc使用简洁的核心理念,将会直接纳入后续的版本升级中,同时源代码和方案提供者也将纳入smart-doc的开发者。
十、祝福
愿你编写接口无数,归来仍是少年
作者:慕先生5555510
链接:http://www.imooc.com/article/71788
来源:慕课网
【转载】Java Restful API 文档生成工具 smart-doc的更多相关文章
- Java 的 Api 文档生成工具 JApiDocs 程序文档工具
JApiDocs 详细介绍 简介 JApiDocs 是一个符合 Java 编程习惯的 Api 文档生成工具.最大程度地利用 Java 的语法特性,你只管用心设计好接口,添加必要的注释,JApiDocs ...
- 工具:使用过的 API 文档生成工具
背景 2012 年之前几乎没有为代码增加注释,当然,代码的命名也不见得合理(好的代码胜过面面俱到的注释),后来接触过一些开源框架,优秀的框架都有一个特点:文档和示例非常多,在后来的日子里,几乎会强制自 ...
- Api文档生成工具与Api文档的传播(pdf)
点击查看apidoc生成文档demo 1 环境和工具 win10 apidoc:注释生成api文档 wkhtmltopdf:apidoc生成的是html,不适合传播,于是通过wkhtmltopdf将h ...
- 推荐开源Api文档生成工具——Doxygen
http://www.stack.nl/~dimitri/doxygen/index.html 非常的方便. 2步生成API文档. 具体信息见官网哟!
- api文档生成工具 C#
要为编写的程序编写文档,这是件费力气的事,如果能自动生成就好了. 不怕做不到,就怕想不到.这不,搜索到了Sandcastle 比较好的参考文章: 1.Sandcastle官方网址: http://sh ...
- [aspnetcore.apidoc]一款很不错的api文档生成工具
AspNetCore.ApiDoc 简单徐速一下为什么选用了aspnetcore.apidoc 而没有选用swagger 最初我们也有在试用swagger,但总是有些感觉,感觉有点不满意,就但从api ...
- 在线API文档管理工具Simple doc
Simple doc是一个简易的文档发布管理工具,为什么要写Simple doc呢?主要原因还是github的wiki并不好用:没有目录结构,文章没有Hx标签索引,最悲剧的是文章编辑的时候不能直接图片 ...
- 如何生成RestFul Api文档
Web API文档工具列表Swagger ——Swagger框架可以通过代码生成漂亮的在线API,甚至可以提供运行示例.支持Scala.Java.Javascript.Ruby.PHP甚至 Actio ...
- Spring Boot 集成 Swagger 生成 RESTful API 文档
原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档 简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...
随机推荐
- python工具的选择
自己喜欢用pycharm,下载地址:https://www.jetbrains.com/products.html#lang=python 补丁地址:http://idea.lanyus.com/
- html5,dom操作1
<body> <script>function hwd(){ var bb=document.getElementById('bt');// alert(bb.innerHTM ...
- 创建servlet程序知识点详解---servlet-day05
jdbc.properties怎么写? 把秘密改为自己电脑设置的 password url 3306 是安装mysql时所确定的端口 后面还可以接字符集的限定 #1 jsp是什么?(java ser ...
- P4027 [NOI2007]货币兑换(斜率优化dp+cdq分治)
P4027 [NOI2007]货币兑换 显然,如果某一天要买券,一定是把钱全部花掉.否则不是最优(攒着干啥) 我们设$f[j]$为第$j$天时用户手上最多有多少钱 设$w$为花完钱买到的$B$券数 $ ...
- Shiro授权管理
一.授权 授权,也叫访问控制,即在应用中控制谁能访问哪些资源(如访问页面/编辑数据/页面操作等).在授权中需了解的几个关键对象:主体(Subject).资源(Resource).权限(Permissi ...
- Python Redis list
List操作,redis中的List在在内存中按照一个name对应一个List来存储. 注:列表存入 从右到左 如图: lpush(name,values) # 在name对应的list中添加元素,每 ...
- Overture里如何添加震音记号
五线谱里的震音记号是指当一个或数个音以相同的时值反复奏响,为了减少乐谱写作中的工作量,而使用的一种省略记号.震音记号用短斜线表示,斜线的数目与演奏时的符尾数目相同. 震音可以分为单震音和复震音两种.单 ...
- kindeditor4.1.11的使用方法
在引入某个外部框架/功能件的 时候, 通常是 先引入css, 后引入js. css的必要属性是rel和href, js的必要属性是charset和src. js都是用javascript的,所以 cs ...
- CSS【03】:CSS 基础选择器与三种引入方式
基础选择器 选择器:css 选择 html 标签的一个工具,是将 css 与 html 建立起联系,那么 css 就可以控制 html 样式 选择器其实就是给 html 标签起名字 标签选择器 作用: ...
- Java三种注释
单行注释:// 注释内容 多行注释:/*... 注释内容....*/ 文本注释:/**.. 注释内容....*/ 这种注释可以用来自动地生成文档.在JDK中有个 ...