JApiDocs真香:以后再也不想用Swagger了

1. 概述

Swagger最麻烦的就是需要在 Controller 上添加一堆 @ApiOperation、@ApiOperation 注解,对代码有一定的侵入性。今天,笔者推荐一个不需要加注解的解决方案。

抱大腿

这就是 JApiDocs ,它可以基于 Controller上的 Java 注释,直接生成接口文档。效果如下图所示:

JApiDocs真香:以后再也不想用Swagger了

效果图

友情提示GitHub 地址是:https://github.com/YeDaxia/JApiDocs 。

2. 快速入门

看完了 JApiDocs 生成的接口文档的效果,我们一起来快速入门下。完整的示例项目,可见 https://github.com/YunaiV/SpringBoot-Labs/tree/master/lab-24/lab-24-apidoc-japidocs 地址,代码如下图所示:

JApiDocs真香:以后再也不想用Swagger了

项目代码

下面,我们来瞅一瞅如何使用~

2.1 引入依赖

在 pom.xml 文件中,引入 japidocs 的依赖。

<dependency>
    <groupId>io.github.yedaxia</groupId>
    <artifactId>japidocs</artifactId>
    <version>1.4.4</version>
</dependency>

2.2 创建 JApiDocs 配置

创建 TestJApiDocs 类,作为 JApiDocs 的配置,生成接口文档。代码如下:

public class TestJApiDocs {

    public static void main(String[] args) {
        // 1. 创建生成文档的配置
        DocsConfig config = new DocsConfig();
        config.setProjectPath("/Users/yunai/Java/SpringBoot-Labs/lab-24/lab-24-apidoc-japidocs"); // 项目所在目录
        config.setDocsPath("/Users/yunai/Downloads/"); // 生成 HTML 接口文档的目标目录
        config.setAutoGenerate(true); // 是否给所有 Controller 生成接口文档
        config.setProjectName("示例项目"); // 项目名
        config.setApiVersion("V1.0"); // API 版本号
        config.addPlugin(new MarkdownDocPlugin()); // 使用 MD 插件,额外生成 MD 格式的接口文档
        // 2. 执行生成 HTML 接口文档
        Docs.buildHtmlDocs(config);
    }

}

偷懒艿:代码比较简单,胖友看下注释,秒懂~

稍后,我们执行 #main(...) 方法,就可以使用 JApiDocs 生成接口文档

2.3 代码注释

JApiDocs 是通过解析 Controller 源码上的 Java 注释,所以我们需要在相关的方法属性上,进行添加。示例代码如下图:

JApiDocs真香:以后再也不想用Swagger了

Java 类

  • UserController
  • UserCreateReqVO
  • UserListReqVO
  • UserRespVO

2.4 简单测试

示例项目搭建完成,我们来简单测试下。

① 执行 TestJApiDocs 类,生成 JApiDocs 接口文档。结果如下图所示:

JApiDocs真香:以后再也不想用Swagger了

生成结果

② 点击 index.html 文件,查看 HTML 接口文档。如下图所示:

JApiDocs真香:以后再也不想用Swagger了

HTML 接口文档

后续,我们可以部署到 Nginx 下,提供给前端小伙伴查看接口文档。

③ 点击 *-api-docs.md 文件,查看 Markdown 接口文档。如下图所示:

JApiDocs真香:以后再也不想用Swagger了

Markdown 接口文档

3. 高级用法

本小节,我们来学习下 JApiDocs 的高级用法。

友情提示:在 99.99% 的场景下,不会使用到,所以胖友可以选择忽略不看。

如果使用到,请胖友直接去锤死狗芳。

JApiDocs 自定义了 @ApiDoc 和 @Ignore 注解,用于针对指定接口,进行自定义的配置。下面,我们来瞅一瞅哦。

良心艿:可能会有胖友说,JApiDocs 的注解不是和 Swagger 的注解一样,也对代码有入侵吗?确实是的,但是比 Swagger 的注解入侵性会低一些,并且基本不需要使用到。

3.1 @ApiDoc 注解

@ApiDoc 注解,声明在接口方法上,通过它的四个属性,进行灵活配置。

  • result 属性:直接声明返回结果的类型。如果你声明了,将会覆盖方法返回结果的类型。
  • stringResult 属性:返回字符串。在返回结果比较简单,而不想创建一个专门的返回类,则可以考虑使用这个属性。友情提示:建议返回结果是否简单,还是创建一个对应的返回类,可维护性更好。
  • url 属性:请求 URL。扩展字段,用于支持非 SpringMVC 的项目。友情提示:JApiDocs 提供了 SpringControllerParser 类,支持解析 SpringMVC 的注解。对于一些老项目,例如说使用 Struts 框架,则需要通过 url 属性来声明。当然,更加推荐自定义一个针对 Struts 的 Parser 解析器,每个接口都手写,挺麻烦的。
  • method 属性:请求 Method。扩展字段,用于支持非 SpringMVC 项目。

@ApiDoc 注解还有一个作用,声明该接口需要导出文档。不过因为一般我们会设置 DocsConfig 的 autoGenerate 属性为 true,默认导出所有 Controller 的接口文档,所以无需使用它。

具体的使用示例如下:

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

// 示例二:针对 `stringResult` 属性
@ApiDoc(stringResult = "{code: 0, data: 'success'}")
@GetMapping(value = "custom-json")
public Map customJsonResult() {}

3.2 @Ignore 注解

@Ignore 注解,比较好理解,实现接口字段的忽略。

具体的使用示例如下:

// 示例一:声明在 Controller 类上,忽略该 Controller 的所有接口
@Ignore
public class UserController {}

// 示例二:声明在接口方法上,忽略该接口
@Ignore
@PostMapping("save")
public ApiResult saveUser() {}

// 示例三:声明在接口使用到的对象的属性上,忽略该属性
public class UserCreateReqVO {
   
   @Ignore
   private Integer age;
   
}

3.3 @description 注释

通过 @description 注释,主要有两种使用场景。

友情提示:由于 @description 注释不是 Java 注释中自带的标签,所以 IDEA 会存在黄色报警的情况,需要手动添加下,去除告警。

① 在 Controller 类上使用 @description 注释,将会作为该 Controller 在接口文档上的导航标题,而不会使用上面的注释内容。示例代码如下:

/**
 * 用户 Controller,提供用户基本信息的 CRUD 的功能
 *
 * @description 用户 API
 */
@Controller
public class UserController {}

② 在接口方法上使用 @description 注释,则可以在接口方法下面额外添加一行说明。示例代码如下:

/**
 * 获得用户列表
 *
 * @param listReqVO 列表筛选条件
 * @return 用户列表
 * @description 不同的前端界面,可能有不同的查询诉求,通过该接口统一满足。
 */
@GetMapping("list")
public List<UserRespVO> list(UserListReqVO listReqVO){
    return null;
}

热门文章

暂无图片
编程学习 ·

C语言二分查找详解

二分查找是一种知名度很高的查找算法&#xff0c;在对有序数列进行查找时效率远高于传统的顺序查找。 下面这张动图对比了二者的效率差距。 二分查找的基本思想就是通过把目标数和当前数列的中间数进行比较&#xff0c;从而确定目标数是在中间数的左边还是右边&#xff0c;将查…
暂无图片
编程学习 ·

GMX 命令分类列表

建模和计算操作命令&#xff1a; 1.1 . 创建拓扑与坐标文件 gmx editconf - 编辑模拟盒子以及写入子组(subgroups) gmx protonate - 结构质子化 gmx x2top - 根据坐标生成原始拓扑文件 gmx solvate - 体系溶剂化 gmx insert-molecules - 将分子插入已有空位 gmx genconf - 增加…
暂无图片
编程学习 ·

一文高效回顾研究生课程《数值分析》重点

数值分析这门课的本质就是用离散的已知点去估计整体&#xff0c;就是由黑盒子产生的结果去估计这个黑盒子。在数学里这个黑盒子就是一个函数嘛&#xff0c;这门课会介绍许多方法去利用离散点最大化地逼近这个函数&#xff0c;甚至它的导数、积分&#xff0c;甚至微分方程的解。…
暂无图片
编程学习 ·

在职阿里5年,一个28岁女软测工程师的心声

简单的先说一下&#xff0c;坐标杭州&#xff0c;14届本科毕业&#xff0c;算上年前在阿里巴巴的面试&#xff0c;一共有面试了有6家公司&#xff08;因为不想请假&#xff0c;因此只是每个晚上去其他公司面试&#xff0c;所以面试的公司比较少&#xff09; ​ 编辑切换为居中…
暂无图片
编程学习 ·

字符串左旋c语言

目录 题目&#xff1a; 解题思路&#xff1a; 第一步&#xff1a; 第二步&#xff1a; 第三步&#xff1a; 总代码&#xff1a; 题目&#xff1a; 实现一个函数&#xff0c;可以左旋字符串中的k个字符。 例如&#xff1a; ABCD左旋一个字符得到BCDA ABCD左旋两个字符…
暂无图片
编程学习 ·

设计模式--观察者模式笔记

模式的定义与特点 观察者&#xff08;Observer&#xff09;模式的定义&#xff1a;指多个对象间存在一对多的依赖关系&#xff0c;当一个对象的状态发生改变时&#xff0c;所有依赖于它的对象都得到通知并被自动更新。这种模式有时又称作发布-订阅模式、模型-视图模式&#xf…
暂无图片
编程学习 ·

睡觉突然身体动不了,什么是睡眠痽痪症

很多朋友可能有这样的体验&#xff0c;睡觉过程中突然意识清醒&#xff0c;身体却动弹不了。这时候感觉非常恐怖&#xff0c;希望旁边有一个人推自己一下。阳光以前也经常会碰到这样的情况&#xff0c;一年有一百多次&#xff0c;那时候很害怕晚上到来&#xff0c;睡觉了就会出…
暂无图片
编程学习 ·

深入理解C++智能指针——浅析MSVC源码

文章目录unique_ptrshared_ptr 与 weak_ptrstd::bad_weak_ptr 异常std::enable_shared_from_thisunique_ptr unique_ptr 是一个只移型别&#xff08;move-only type&#xff0c;只移型别还有std::mutex等&#xff09;。 结合一下工厂模式&#xff0c;看看其基本用法&#xff…
暂无图片
编程学习 ·

@TableField(exist = false)

TableField(exist false) //申明此字段不在数据库存在&#xff0c;但代码中需要用到它&#xff0c;通知Mybatis-plus在做写库操作是忽略它。,.
暂无图片
编程学习 ·

Java Web day15

第十二章文件上传和下载 一、如何实现文件上传 要实现Web开发中的文件上传功能&#xff0c;通常需要完成两步操作&#xff1a;一.是在Web页面中添加上传输入项&#xff1b;二是在Servlet中读取上传文件的数据&#xff0c;并保存到本地硬盘中。 需要使用一个Apache组织提供一个…
暂无图片
编程学习 ·

【51nod 2478】【单调栈】【前缀和】小b接水

小b接水题目解题思路Code51nod 2478 小b接水 题目 输入样例 12 0 1 0 2 1 0 1 3 2 1 2 1输出样例 6解题思路 可以发现最后能拦住水的都是向两边递减高度&#xff08;&#xff1f;&#xff09; 不管两个高积木之间的的积木是怎样乱七八糟的高度&#xff0c;最后能用来装水的…
暂无图片
编程学习 ·

花了大半天写了一个UVC扩展单元调试工具

基于DIRECTSHOW 实现的&#xff0c;用的是MFC VS2019. 详见&#xff1a;http://www.usbzh.com/article/detail-761.html 获取方法 加QQ群:952873936&#xff0c;然后在群文件\USB调试工具&测试软件\UVCXU-V1.0(UVC扩展单元调试工具-USB中文网官方版).exe USB中文网 USB中文…
暂无图片
编程学习 ·

贪心(一):区间问题、Huffman树

区间问题 例题一&#xff1a;区间选点 给定 N 个闭区间 [ai,bi]请你在数轴上选择尽量少的点&#xff0c;使得每个区间内至少包含一个选出的点。 输出选择的点的最小数量。 位于区间端点上的点也算作区间内。 输入格式 第一行包含整数 N&#xff0c;表示区间数。 接下来 …
暂无图片
编程学习 ·

C语言练习实例——费氏数列

目录 题目 解法 输出结果 题目 Fibonacci为1200年代的欧洲数学家&#xff0c;在他的着作中曾经提到&#xff1a;「若有一只免子每个月生一只小免子&#xff0c;一个月后小免子也开始生产。起初只有一只免子&#xff0c;一个月后就有两只免子&#xff0c;二个月后有三只免子…
暂无图片
编程学习 ·

Android开发(2): Android 资源

个人笔记整理 Android 资源 Android中的资源&#xff0c;一般分为两类&#xff1a; 系统内置资源&#xff1a;Android SDK中所提供的已经定义好的资源&#xff0c;用户可以直接拿来使用。 用户自定义资源&#xff1a;用户自己定义或引入的&#xff0c;只适用于当前应用的资源…
暂无图片
编程学习 ·

零基础如何在短时间内拿到算法offer

​算法工程师是利用算法处理事物的职业 算法&#xff08;Algorithm&#xff09;是一系列解决问题的清晰指令&#xff0c;也就是说&#xff0c;能够对一定规范的输入&#xff0c;在有限时间内获得所要求的输出。 如果一个算法有缺陷&#xff0c;或不适合于某个问题&#xff0c;执…
暂无图片
编程学习 ·

人工智能:知识图谱实战总结

人工智能python&#xff0c;NLP&#xff0c;知识图谱&#xff0c;机器学习&#xff0c;深度学习人工智能&#xff1a;知识图谱实战前言一、实体建模工具Protegepython&#xff0c;NLP&#xff0c;知识图谱&#xff0c;机器学习&#xff0c;深度学习 人工智能&#xff1a;知识图…
暂无图片
编程学习 ·

【无标题】

这里写自定义目录标题欢迎使用Markdown编辑器新的改变功能快捷键合理的创建标题&#xff0c;有助于目录的生成如何改变文本的样式插入链接与图片如何插入一段漂亮的代码片生成一个适合你的列表创建一个表格设定内容居中、居左、居右SmartyPants创建一个自定义列表如何创建一个注…