再见,Swagger(丝袜哥)!

Python网络爬虫与数据挖掘

共 2298字,需浏览 5分钟

 ·

2020-08-25 23:15

转载自公众号【coder_love】

关于接口文档生成工具之前一直都是再用丝袜哥,但是最新我另觅新欢了!
JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。
编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又不得不做的事情,我们都不喜欢写文档,但除非项目前后端代码都是自己写的,否则API文档将是前后端协作中一个不可或缺的沟通界面。既然不可避免,那就想办法弄个轮子吧。人生苦短,必须偷懒。
无图无真相,生成文档的效果如下:

相比Swagger要写一堆注解,Spring RestDocs需要写测试用例,才能生成API文档。JApiDocs 具有无痛集成的特点,你只需花几分钟就能知道它怎么用了。

快速开始


要使得JApiDcos正确工作,你写的代码应该是像下面的样子的:
/**
* 用户接口
*/
@RequestMapping("/api/user/")
@RestController
public class UserController {
/**
* 用户列表
* @param listForm
*/
@RequestMapping(path = "list", method = {RequestMethod.GET, RequestMethod.POST} )
public ApiResult> list(UserListForm listForm){
return null;
}

/**
* 保存用户
* @param userForm
*/
@PostMapping(path = "save")
public ApiResult saveUser(@RequestBody UserForm userForm){
return null;
}
}


我们给Controller类和方法加上必要的注释,给接口方法返回相关的对象类型。是的,这样JApiDocs就能解析到相关的接口信息了,就跟我们平时写的代码是差不多的,但要注意,你要通过@param来告诉JApiDocs接口的参数,但在IDE的帮助下,这个工作将是轻松愉悦的:

然后你在任意一个main入口方法执行下面的代码就可以生成文档了:
DocsConfig config = new DocsConfig();
config.setProjectPath("your springboot project path"); // 项目根目录
config.setProjectName("ProjectName"); // 项目名称
config.setApiVersion("V1.0"); // 声明该API的版本
config.setDocsPath("your api docs path"); // 生成API 文档所在目录
config.setAutoGenerate(Boolean.TRUE); // 配置自动生成
Docs.buildHtmlDocs(config); // 执行生成文档
接下来你只管好好写代码,生成Api文档的工作就可以交给JApiDocs了,你不需要再为额外编写和维护文档而烦恼。

功能特性


1、代码即文档
JApiDocs是通过直接解析SpringBoot的源码语法来工作的,所以只要Controller的语法符合一定的代码规范,有合理的注释,就可以直接导出文档。
2、支持导出HTML
便捷的导航和接口查看界面;可本地预览,或者部署到HTTP服务器。推荐部署到服务器,方便前后端展开协作。
3、同步导出客户端Model代码
支持导出Android端的 Java 和iOS端的 Object C Model代码,减少前端程序员的重复编码工作。
4、更多特性
支持接口搜索;支持不同版本和英文文档;自定义扩展等。

简洁的文档


再好用的东西,如果没有文档说明,别人也无从入手。为了让大家尽快上手,JApiDocs准备了一份极简的文档说明,确保你在几分钟就能用上JApiDocs。花5分钟不到就能认识一个提高工作效率的工具,让你把更多的时间花在更加有价值的事情上,你确认不看一下吗?
仓库地址:https://github.com/YeDaxia/JApiDocs
中文文档:https://japidocs.agilestudio.cn/#/zh-cn/




说个题外话,鸟哥是个比较喜欢折腾的程序员,业余喜欢开发自己网站、小程序、App等,这些东西统统离不开服务器!最近就围绕服务器的主题创建了一个微信群,喜欢玩服务器或者想自己开发一款产品的读者可以进来,相互学习交流!我也会时不时的带大家撸点和服务器相关的优惠券!不感兴趣,不喜欢折腾的就没必要凑着闹了!



回复下方「关键词」,获取优质资源


回复关键词「简明python」,立即获取入门必备书籍简明python教程》电子版

回复关键词「爬虫」,立即获取爬虫学习资料



推荐阅读



请拼命点赞

浏览 8
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报
评论
图片
表情
推荐
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报