0
  • 聊天消息
  • 系统消息
  • 评论与回复
登录后你可以
  • 下载海量资料
  • 学习在线课程
  • 观看威廉希尔官方网站 视频
  • 写文章/发帖/加入社区
会员中心
创作中心

完善资料让更多小伙伴认识你,还能领取20积分哦,立即完善>

3天内不再提示

一个无需注解的SpringBoot API文档生成神器

Android编程精选 来源:TJ君 2023-03-13 09:38 次阅读

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

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

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

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

babe629c-c13b-11ed-bfe3-dac502259ad0.png

功能特性

1、代码即文档

JApiDocs是通过直接解析SpringBoot的源码语法来工作的,所以只要Controller的语法符合一定的代码规范,有合理的注释,就可以直接导出文档。

2、支持导出HTML

便捷的导航和接口查看界面;可本地预览,或者部署到HTTP服务器。推荐部署到服务器,方便前后端展开协作。

3、同步导出客户端Model代码

支持导出Android端的 JavaiOS端的 Object C Model代码,减少前端程序员的重复编码工作。

4、更多特性

支持接口搜索;支持不同版本和英文文档;自定义扩展等。

简洁的文档

再好用的东西,如果没有文档说明,别人也无从入手。为了让大家尽快上手,JApiDocs准备了一份极简的文档说明,确保你在几分钟就能用上JApiDocs。

花5分钟不到就能认识一个提高工作效率的工具,让你把更多的时间花在更加有价值的事情上,你确认不看一下吗?

  • 仓库地址:https://github.com/YeDaxia/JApiDocs
  • 中文文档:https://japidocs.agilestudio.cn/#/zh-cn/

支持接口搜索;支持不同版本和英文文档;自定义扩展等。

入门

支持JDK:1.8+

快速开始

第一步:添加依赖

maven:

<dependency>
<groupId>io.github.yedaxiagroupId>
<artifactId>japidocsartifactId>
<version>1.3version>
dependency>

gradle:

compile'io.github.yedaxia1.3'
第二步:配置参数

你可以在任意一个main入口运行下面的代码:

DocsConfigconfig=newDocsConfig();
config.setProjectPath("yourspringbootprojectpath");//项目根目录
config.setProjectName("ProjectName");//项目名称
config.setApiVersion("V1.0");//声明该API的版本
config.setDocsPath("yourapidocspath");//生成API文档所在目录
config.setAutoGenerate(Boolean.TRUE);//配置自动生成
Docs.buildHtmlDocs(config);//执行生成文档

如果没有意外,执行完上面的代码后,你就可以在配置的目录中看到生成的文档了。

编码规范

JApiDocs是通过解析Java源码来实现的,要使得JApiDocs正确工作,需要你在项目中的Controller书写遵循一定的编码规范。

你可以结合源码中 SpringDemo 这个模块来对照理解。

1. 添加必要的代码注释

其中类注释会对应到一级接口分组,你也可以通过@description来指定分组名称;JApiDocs 会通过 @param 来寻找接口参数和进一步解析参数的内容。

/**
*用户接口
*/
@RequestMapping("/api/user/")
@RestController
publicclassUserController{

/**
*用户列表
*@paramlistForm
*/
@RequestMapping(path="list",method={RequestMethod.GET,RequestMethod.POST})
publicApiResult>list(UserListFormlistForm){
returnnull;
}

/**
*保存用户
*@paramuserForm
*/
@PostMapping(path="save")
publicApiResultsaveUser(@RequestBodyUserFormuserForm){
returnnull;
}

/**
*删除用户
*@paramuserId用户ID
*/
@PostMapping("delete")
publicApiResultdeleteUser(@RequestParamLonguserId){
returnnull;
}
}

如果提交的表单是 application/x-www-form-urlencoded 类型的key/value格式,你可以在 SpringBoot 端通过在 @param 参数后添加字段解释或者在相关的JavaBean对象里面添加解释:

//直接在java的@param注解中
@paramuserId用户ID
//在FormBean对象中
publicclassUserListFormextendsPageForm{
privateIntegerstatus;//用户状态
privateStringname;//用户名
}

这种格式对于到文档中的参数描述将是表格的形式:

baf58cfe-c13b-11ed-bfe3-dac502259ad0.png

如果提交的表单是 application/json 类型的json数据格式,对应 SpringBoot 中的 @RequestBody 注解,在文档中则是 json 格式显示:

{
"id":"long//用户ID",
"name":"string//用户名",
"phone":"long//电话",
"avatar":"string//头像",
"gender":"byte//性别"
}
2. 接口声明返回对象

我们知道,如果Controller声明了@RestController,SpringBoot会把返回的对象直接序列成Json数据格式返回给前端。JApiDocs也利用了这一特性来解析接口返回的结果,但由于JApiDocs是静态解析源码的,因此你要明确指出返回对象的类型信息,JApiDocs支持继承、泛型、循环嵌套等复杂的类解析。

比如上面的saveUser接口:

/**
*保存用户
*@paramuserForm
*/
@PostMapping(path="save")
publicApiResultsaveUser(@RequestBodyUserFormuserForm){
returnnull;
}

ApiResult表明了该接口返回的数据结构,经过JApiDocs处理后是这样的:

{
"code":"int",
"errMsg":"string",
"data":{
"userId":"string//用户id",
"userName":"string//用户名",
"friends":[
{
"userId":"string//用户id",
"userName":"string//用户名"
}
],
"readBooks":[
{
"bookId":"long//图书id",
"bookName":"string//图书名称"
}
],
"isFollow":"boolean//是否关注"
}
}

如果你不是通过返回对象的形式,你也可以通过JApiDocs提供的@ApiDoc注解来声明返回类型,你可以参考@ApiDoc章节的相关配置内容。

3. 接口对象在源码中

我们知道,经过编译后的 class 字节码中是没有注释信息的,如果要通过反射字节码的方式来实现,则不可避免要引入运行时注解,这样会增加使用成本, 考虑到这一点,JApiDocs 从第二个版本之后就改成了使用解析源码的方式,而不是反射字节码的思路来实现了,但这样直接导致的缺陷就是:所有的 Form Bean (表单)对象和返回对象就必须在项目的源码中,否则就无法解析了,如果你们项目的JavaBean对象是通过jar包的形式提供的, 那很遗憾,JApiDocs将无法支持。

高级配置

@ApiDoc

JApiDocs 默认只导出声明了@ApiDoc的接口,我们前面通过设置 config.setAutoGenerate(Boolean.TRUE) 来解除了这个限制。

如果你不希望把所有的接口都导出,你可以把autoGenerate设置关闭,在相关Controller类或者接口方法上通过添加@ApiDoc来确定哪些接口需要导出。

@ApiDoc声明在接口方法上的时候,它还拥有一些更灵活的设置,下面我们来看一下:

  • result: 这个可以直接声明返回的对象类型,如果你声明了,将会覆盖SpringBoot的返回对象
  • url: 请求URL,扩展字段,用于支持非SpringBoot项目
  • method: 请求方法,扩展字段,用于支持非SpringBoot项目

例子:

@ApiDoc(result=AdminVO.class,url="/api/v1/admin/login2",method="post")
@Ignore

如果你不想导出对象里面的某个字段,可以给这个字段加上@Ignore注解,这样JApiDocs导出文档的时候就会自动忽略掉了:

例子:

publicclassUserForm{
@Ignore
privateBytegender;//性别
}

自定义代码模板

JApiDocs 除了支持文档导出,目前也支持生成了 Android 和 iOS 的返回对象代码,对应 Java 和 Object-C 语言, 如果你想修改代码模板,可以通过以下的方法:

第一步:定义代码模板

把源码中library项目resources目录下的代码模板拷贝一份,其中,IOS_表示 Object-C 代码模板,JAVA_开头表示 Java代码, 模板中类似${CLASS_NAME}的符号是替换变量,具体含义你可以结合生成的代码进行理解,然后按照你想要的代码模板进行修改即可。

第二步:选择新的模板

通过DocsConfig配置模板路径替换成新的模板:

docsConfig.setCodeTplPath("模板路径");

添加更多功能

JApiDocs 提供了插件接口,你可以通过插件接口来实现更多丰富的功能,下面介绍如何添加插件:

第一步:实现 IPluginSupport 接口
publicclassCustomPluginimplementsIPluginSupport{

@Override
publicvoidexecute(ListcontrollerNodeList){
//实现你自己的功能需求
}
}
第二步:添加插件
config.addPlugin(newCustomPlugin());
审核编辑 :李倩
声明:本文内容及配图由入驻作者撰写或者入驻合作网站授权转载。文章观点仅代表作者本人,不代表电子发烧友网立场。文章及其配图仅供工程师学习之用,如有内容侵权或者其他违规问题,请联系本站处理。 举报投诉
  • API
    API
    +关注

    关注

    2

    文章

    1499

    浏览量

    61969
  • HTML
    +关注

    关注

    0

    文章

    278

    浏览量

    35215
  • 源码
    +关注

    关注

    8

    文章

    639

    浏览量

    29185
  • SpringBoot
    +关注

    关注

    0

    文章

    173

    浏览量

    177

原文标题:一个无需注解的 SpringBoot API文档生成神器,相当哇塞!

文章出处:【微信号:AndroidPush,微信公众号:Android编程精选】欢迎添加关注!文章转载请注明出处。

收藏 人收藏

    评论

    相关推荐

    如何使用SpringBoot集成Netty开发基于WebSocket的聊天室说明

    文档的主要内容详细介绍的是基于SpringBoot,借助Netty控制长链接,使用WebSocket协议做一个实时的聊天室。
    发表于 05-29 17:56 1次下载
    如何使用<b class='flag-5'>SpringBoot</b>集成Netty开发<b class='flag-5'>一</b><b class='flag-5'>个</b>基于WebSocket的聊天室说明

    Spring Boot的注解原理是什么

    @SpringBootApplication来看,发现@SpringBootApplication是组合注解。 @Target(ElementType.TYPE) @Retention
    的头像 发表于 08-27 09:24 2192次阅读

    文档生成工具:Doxygen生成

    有了配置文件后我们完全可以通过命令行来生成API文档,假设配置文件名为Doxyfile,那么我们只需要执行doxygen /path/to/Doxyfile即可生成
    的头像 发表于 04-27 09:15 2363次阅读

    如何设计优雅的API接口

    种是API接口提供方给出AK/SK两值,双方约定用SK作为签名中的密钥。AK接口调用方作为header中的accessKey传递给API接口提供方,这样
    的头像 发表于 12-20 14:23 1616次阅读

    SpringBoot定时任务动态管理通用解决方案

    SpringBoot的定时任务的加强工具,实现对SpringBoot原生的定时任务进行动态管理,完全兼容原生@Scheduled注解,无需对原本的定时任务进行修改
    的头像 发表于 02-03 09:49 774次阅读

    什么是 SpringBoot

    本文从为什么要有 `SpringBoot`,以及 `SpringBoot` 到底方便在哪里开始入手,逐步分析了 `SpringBoot` 自动装配的原理,最后手写了
    的头像 发表于 04-07 11:28 1306次阅读
    什么是 <b class='flag-5'>SpringBoot</b>?

    SpringBoot常用注解及使用方法1

    基于 SpringBoot 平台开发的项目数不胜数,与常规的基于`Spring`开发的项目最大的不同之处,SpringBoot 里面提供了大量的注解用于快速开发,而且非常简单,基本可以做到开箱即用! 那
    的头像 发表于 04-07 11:51 699次阅读

    SpringBoot常用注解及使用方法2

    基于 SpringBoot 平台开发的项目数不胜数,与常规的基于Spring开发的项目最大的不同之处,SpringBoot 里面提供了大量的注解用于快速开发,而且非常简单,基本可以做到开箱即用!
    的头像 发表于 04-07 11:52 676次阅读

    Springboot常用注解合集

    前几章,在系统启动类里面,都加入了此启动注解,此注解组合注解,包括了`@SpringBootConfiguration`、`@EnableAutoConfiguration`和`@
    的头像 发表于 04-07 14:27 733次阅读
    <b class='flag-5'>Springboot</b>常用<b class='flag-5'>注解</b>合集

    SpringBoot常用注解及原理

    SpringBootConfiguration继承自@Configuration,二者功能也致,标注当前类是配置类, 并会将当前类内声明的或多个以@Bean注解标记的方法的实例纳
    的头像 发表于 04-07 14:30 582次阅读

    SpringBoot的核心注解1

    今天跟大家来探讨下SpringBoot的核心注解@SpringBootApplication以及run方法,理解下springBoot为什么不需要XML,达到零配置
    的头像 发表于 04-07 14:34 701次阅读
    <b class='flag-5'>SpringBoot</b>的核心<b class='flag-5'>注解</b>1

    SpringBoot的核心注解2

    今天跟大家来探讨下SpringBoot的核心注解@SpringBootApplication以及run方法,理解下springBoot为什么不需要XML,达到零配置
    的头像 发表于 04-07 14:34 1958次阅读
    <b class='flag-5'>SpringBoot</b>的核心<b class='flag-5'>注解</b>2

    springboot核心注解

    Spring Boot 是基于 Spring 框架的开源框架,它可以帮助开发者快速构建、部署和运行独立的、生产级的 Spring 应用程序。Spring Boot 提供了系列核心注解,这些注解可以
    的头像 发表于 11-23 09:23 513次阅读

    注解搞定SpringBoot接口防刷

    威廉希尔官方网站 要点:springboot的基本知识,redis基本操作,
    的头像 发表于 11-28 10:46 404次阅读

    SpringBoot核心注解由几个注解组成

    等。本文将详尽介绍这些核心注解。 @SpringBootApplication @SpringBootApplication 是复合注解,包含了 @Configuration、@
    的头像 发表于 12-03 15:09 755次阅读