文档章节

如何快速实现spring boot技术栈api文档的生成

上官胡闹
 上官胡闹
发布于 02/17 13:25
字数 1680
阅读 6.3K
收藏 12

作为开发,写接口文档一直是一个很头痛的问题,尤其在前后端分离大量盛行的当下,后端必须要为前端同事提供明确的入参出参文档,否则整个对接工作无法顺利进行,前后端的相爱相杀的大戏时常上演。笔者刚工作的那些年,swagger都还没有正式发布,对接前端和app端的文档全靠手写markdown完成。写接口文档的时间常常感jio比写代码耗费的时间还长。随着技术的进步和众多开源人的努力,近几年针对java开发的文档生成工具越来越多。新入行的开发人员再也不用去体会过去的那些辛酸历程。在java文档生成的这个领域,swagger一直是一只领头羊。可能占据着90%的市场, 除此还有像 Spring REST Doc这些有名的工具也被大量的使用,但是这些工具在笔者看来使用比较蛮烦,侵入性高。今天笔者要给大家介绍和推荐一款本人开源的文档工具smart-doc,也会介绍如何使用这个工具来生成自己的文档。

一、当前市面上文档工具存在的问题

下面来列举当前市场上主流文档工具的问题:

  • 侵入性强,需要编写大量注解,代表工具如:swagger,还有一些公司自研的文档工具
  • 强依赖性,如果项目不想使用该工具,业务代码无法编译通过。
  • 代码解析能力弱,使用文档不齐全,主要代表为国内众多开源的相关工具。
  • 众多基于注释分析的工具无法解析jar包里面的注释(sources jar包),需要人工配置源码路径,无法满足DevOps构建场景。
  • 无法支持多模块复杂项目代码分析。

二、smart-doc如何解决上述问题

  • 通过分析源码注释自动生成API文档,不用编写任何注解,秉承注释即文档的原则,并且提供注释强制检查。
  • smart-doc开发了smart-doc-maven-plugin插件,项目仅仅依赖插件,剔除插件无修改项目不报任何编译错误。
  • smart-doc在国内经过上百家企业的使用,做了很多场景的分析,解析能力很强。
  • smart-doc-maven-plugin插件自动分析项目依赖,自动完成对自发布jar包和第三方jar包源码的加载,不需要指定任何源码路径。
  • smart-doc-maven-plugin能够识别项目依赖,多模块maven项目不是问题。
  • smart-doc文档维护比较完善,码云上的wiki有16个页面介绍各种使用方式。

关于smart-doc

三、smar-doc的不足

smart-doc并非是完美的,仍然有很多不足。

  • 界面支持不完善,没有发送请求的页面,无法满足小团队自测。
  • 一些使用场景支持不完善,存在一些bug。
  • 暂不支持其他框架文档的生成,如:dubbo等。
  • 开源团队人员少,功能实现慢。
  • 当前缺乏gradle插件支持。

四、spring boot集成smart-doc生成文档。

上面说了关于一起其它工具的问题,也介绍了smart-doc的优缺点,下面进入正题,如何快速使用smart-doc生成文档。

4.1 添加插件

在spring boot项目pom中添加smart-doc的maven插件

 <plugin>
	<groupId>com.github.shalousun</groupId>
	<artifactId>smart-doc-maven-plugin</artifactId>
	<version>[最新版本]</version>
	<configuration>
		<!--指定生成文档使用的配置文件-->
		<configFile>./src/main/resources/smart-doc.json</configFile>
	</configuration>
	<executions>
		<execution>
 			<!--不需要在编译项目时自动生成文档可注释phase-->
			<phase>compile</phase>
			<goals>
				<goal>html</goal>
			</goals>
		</execution>
	</executions>
</plugin>

4.2 添加smart-doc.json配置文件

在4.1的代码片段中看到需要给插件指定一个生成文档的配置文件smart-doc.json。文件内容如下:

{
  "serverUrl": "http://127.0.0.1",//服务器地址
  "isStrict": false,//是否用严格模式,严格模式强制检查注释
  "allInOne": true,//所有接口文档合并生成到一个文档
  "outPath": "src/main/resources/static/doc",//文档的输出路径
  "projectName": "smart-doc"//指定项目名称,用于显示在文档中
}

上面的几行配置中,实际上只有outPath是必须要的,其他都是非必须。相比其它工具,smart-doc配置简单又不会影响到项目。想了解更多详细配置请参考smart-doc插件使用

4.3 编写controller接口

@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 添加用户
     * @param user
     * @return
     */
    @PostMapping("/add")
    public User addUser(@RequestBody User user){
        return user;
    }
}

实体类:

public class User {

    /**
     * 用户名
     */
    private String userName;

    /**
     * 昵称
     */
    private String nickName;

    /**
     * 用户地址
     */
    private String userAddress;

    /**
     * 用户年龄
     */
    private int userAge;

    /**
     * 手机号
     */
    private String phone;

    /**
     * 创建时间
     */
    private Long createTime;

    /**
     * ipv6
     */
    private String ipv6;

    /**
     * 固定电话
     */
    private String telephone;
    //省略get set
}

4.4 运行插件生成文档

idea中smart-doc-maven插件使用

效果见4.5

4.5 用户信息操作接口

添加用户

URL:http://localhost:8080/user/add

Type:POST

Content-Type:application/json; charset=utf-8

Request-parameters:

Parameter Type Description Required Since
userName string 用户名 false -
nickName string 昵称 false -
userAddress string 用户地址 false -
userAge int 用户年龄 false -
phone string 手机号 false -
createTime number 创建时间 false -
ipv6 string ipv6 false -
telephone string 固定电话 false -

Request-example:

{
    "userName":"鹏飞.贺",
    "nickName":"raymond.gutkowski",
    "userAddress":"Apt. 819 萧旁7699号, 章丘, 滇 852063",
    "userAge":41,
    "phone":"15018373016",
    "createTime":1569934393095,
    "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
    "telephone":"15018373016"
}

Response-fields:

Field Type Description Since
userName string 用户名 -
nickName string 昵称 -
userAddress string 用户地址 -
userAge int 用户年龄 -
phone string 手机号 -
createTime number 创建时间 -
ipv6 string ipv6 -
telephone string 固定电话 -

Response-example:

{
    "userName":"鹏飞.贺",
    "nickName":"raymond.gutkowski",
    "userAddress":"Apt. 819 萧旁7699号, 章丘, 滇 852063",
    "userAge":41,
    "phone":"15018373016",
    "createTime":1569934393095,
    "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
    "telephone":"15018373016"
}

总结

当前最新的smart-doc结合插件后,已经做到了非常易于使用,只需要引入插件和根据自己需求填充相关的配置即可,非常的轻量级。将smart-doc推荐给大家是为了帮助更多的同行能够快速的生成api文档,也是给一些正在自研的同行提供一些实现思路。想要参与贡献,帮助smart-doc不断完善的开发者,我们也非常欢迎加入。如果您喜欢smart-doc,请记得为我们项目点赞,您的支持是我们一直开源的动力!!!

© 著作权归作者所有

上官胡闹

上官胡闹

粉丝 78
博文 91
码字总数 65842
作品 1
成都
高级程序员
私信 提问
加载中

评论(1)

《Spring Boot 入门及前后端分离项目实践》系列介绍

课程计划 课程地址点这里 本课程是一个 Spring Boot 技术栈的实战类课程,课程共分为 3 个部分,前面两个部分为基础环境准备和相关概念介绍,第三个部分是 Spring Boot 项目实践开发。Sprin...

我是13
2019/03/25
0
0
Spring Boot 集成 Swagger,生成接口文档就这么简单!

之前的文章介绍了《推荐一款接口 API 设计神器!》,今天栈长给大家介绍下如何与优秀的 Spring Boot 框架进行集成,简直不能太简单。 你所需具备的基础 告诉你,Spring Boot 真是个牛逼货! ...

Java技术栈
2019/03/19
196
0
Spring Cloud Eureka 注册中心集群搭建,Greenwich 最新版!

Spring Cloud 的注册中心可以由 Eureka、Consul、Zookeeper、ETCD 等来实现,这里推荐使用 Spring Cloud Eureka 来实现注册中心,它基于 Netflix 的 Eureka 做了二次封装,完成分布式服务中服...

Java技术栈
2019/04/03
199
0
年轻人的第一个 Spring Boot 应用,太爽了!

Spring Boot 大家都知道是啥吧? 还有不知道的来看这篇扫下盲:告诉你,Spring Boot 真是个牛逼货!。 顺便再往下看,栈长给你带来年轻人的第一个 Spring Boot 应用,撸码史无前例的轻松,那...

Java技术栈
2019/06/24
170
0
renren-security-boot v2.0.0 发布,J2EE 快速开发平台

renren-security-boot是基于renren-security,用Spring Boot实现的J2EE快速开发平台,其核心设计目标是开发迅速、学习简单、轻量级、易扩展,方便二次开发! v2.0版本更新日志: 实现前后端完...

独孤求胜16
2017/04/21
2.3K
5

没有更多内容

加载失败,请刷新页面

加载更多

Word文档中遇到不认识的字怎么办?word 2019 for Mac自带拼音功能你知道吗?

Word 2019 for Mac中遇到不认识的字怎么办?你是不是要告诉我,找百度!那如果没有网又该怎么办? 经常接触文档,总会遇到很多不认识的字,不用百度只用Word也能快速读对,一起来学学吧! wo...

mac小叮当
17分钟前
7
0
docker下mysql8版本的安装运行及navicat的连接

一、下载 $ docker pull mysql:8.0.19 一般来说这个速度是比较慢的,我试了几次都不行,只好换一个国内的镜像: $ mkdier -p /etc/docker$ tee /etc/docker/daemon.json << 'EOF'{ 'r......

最深的夜
22分钟前
5
0
游戏音频未来发展趋势

游戏音频根据各自声音特点可以分为:游戏音乐、音效与配音。无论是游戏音乐、游戏音效还是 游戏配音对于游戏有着极其重要的作用,那么未来游戏音频将会有什么样的发展趋势呢?跟着小编一起来...

奇亿音乐
23分钟前
10
0
harbor安装使用

1. 先安装环境docker docker-compose 2. 从https://github.com/goharbor/harbor/releases 下载最新的。 如harbor-online-installer-v1.10.2.tgz 3. 解压 tar -xvf harbor-online-installer......

杰仪
30分钟前
14
0
服务器一般需要打开哪些端口?

一般我们只开放常用的端口号。例如,20,21,23,80等。   21:FTP服务所开放的端口,用于上传、下载文件。   22:SSH端口,用于通过命令行模式远程连接Linux服务器或vps。   23:Tel...

Cloudam云端
31分钟前
12
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部