文档章节

还在用Swagger(丝袜哥)生成接口文档?我推荐你试试它.....

路人甲Java
 路人甲Java
发布于 07/09 16:30
字数 1162
阅读 66
收藏 0

「深度学习福利」大神带你进阶工程师,立即查看>>>



JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。

编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又不得不做的事情,我们都不喜欢写文档,但除非项目前后端代码都是自己写的,否则API文档将是前后端协作中一个不可或缺的沟通界面。

既然不可避免,那就想办法弄个轮子吧。人生苦短,必须偷懒。

无图无真相,生成文档的效果如下:

img

相比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<PageResult<UserVO>> list(UserListForm listForm){
return null;
}

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

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

img

然后你在任意一个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/


      
      

更多好文章

  1. Java高并发系列(共34篇)

  2. MySql高手系列(共27篇)

  3. Maven高手系列(共10篇)

  4. Mybatis系列(共12篇)

  5. 聊聊db和缓存一致性常见的实现方式

  6. 接口幂等性这么重要,它是什么?怎么实现?

  7. 泛型,有点难度,会让很多人懵逼,那是因为你没有看这篇文章!



世界上最好的关系是相互成就,点赞转发 感恩开心😃




路人甲java

▲长按图片识别二维码关注


路人甲Java:工作10年的前阿里P7,所有文章以系列的方式呈现,带领大家成为java高手,目前已出:java高并发系列、mysql高手系列、Maven高手系列、mybatis系列、spring系列,正在连载springcloud系列,欢迎关注!


本文分享自微信公众号 - 路人甲Java(javacode2018)。
如有侵权,请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”,欢迎正在阅读的你也加入,一起分享。

路人甲Java
粉丝 32
博文 301
码字总数 588205
作品 0
闵行
技术主管
私信 提问
加载中
请先登录后再评论。
beego API开发以及自动化文档

beego API开发以及自动化文档 beego1.3版本已经在上个星期发布了,但是还是有很多人不了解如何来进行开发,也是在一步一步的测试中开发,期间QQ群里面很多人都问我如何开发,我的业余时间实在...

astaxie
2014/06/25
2.7W
22
5分钟 maven3 快速入门指南

前提条件 你首先需要了解如何在电脑上安装软件。如果你不知道如何做到这一点,请询问你办公室,学校里的人,或花钱找人来解释这个给你。 不建议给Maven的服务邮箱来发邮件寻求支持。 安装Mav...

fanl1982
2014/01/23
1.2W
7
代码生成器--Codgen

Codgen是一个基于数据库元数据模型,使用freemarker模板引擎来构建输出的代码生成器。freemarker的数据模型结构通常来说都是一个Map树状结构模型,codgen也不例外,它的数据模型这棵树的根节...

黄天政
2013/01/29
1.4W
2
Hbase的Windows访问接口库--libhbase4win

libhbase4win是基于Thrift的Hbase的Windows访问接口库,开发工具使用VS2010,Hadoop版本为1.1.0,Hbase版本为0.94.0,thrift版本0.9.0,执行编译需要boost和thrift支持。...

张子良
2013/03/06
764
0
阿里云开放存储服务的C语言SDK--OSSC

OSSC(Aliyun Open Storage Service C SDK)为阿里云开放存储服务(OSS)提供了一套完整易用的C SDK。 OSSC完全采用C语言开发,并实现了类似面向对象的调用方式,遵循了良好的编码规范,目前O...

大卷卷
2012/10/22
4.6K
0

没有更多内容

加载失败,请刷新页面

加载更多

从JS数组中删除重复的值[duplicate] - Remove duplicate values from JS array [duplicate]

问题: This question already has answers here : 这个问题已经在这里有了答案 : Get all unique values in a JavaScript array (remove duplicates) (79 answers) 获取JavaScript数组中的......

法国红酒甜
今天
3
0
如何使用AngularJS在浏览器的控制台中访问$ scope变量?

问题: I would like to access my $scope variable in Chrome's JavaScript console. 我想在Chrome的JavaScript控制台中访问$scope变量。 How do I do that? 我怎么做? I can neither see ......

fyin1314
今天
18
0
ImageMagick - 添加水印

背景 最近制作思维导图想添加自己的水印,网上很多例子都是使用ImageMagick来完成。但是不少代码在本地并不可行。经过一番试验,找到两个方法。 方法一 代码 stackoverflow方法改良: conver...

wffger
今天
11
0
OSChina 周四乱弹 —— 到底是怎样的饕餮盛宴在等待着我!

Osc乱弹歌单(2020)请戳(这里) 【今日歌曲】 小小编辑推荐 :《你 能 來 保 護 我 的 世 界 嘛》- 歪门 《你 能 來 保 護 我 的 世 界 嘛》- 歪门 手机党少年们想听歌,请使劲儿戳(这里)...

小小编辑
今天
77
0
C程序调试与GDB入门

[TOC] 1、Assert 引用自<assert.h>的函数assert(int expression),当表达式的值为0则返回failed。 2、GDB gdb是GUN的提供在unix上的调试工具。 安装:sudo apt install gdb 如果是windows,则...

小小怪医芙兰
今天
23
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部