Java Restful API 文档生成工具 smart-doc

2023年2月9日 247次阅读 
谁说生成api文档就必须要定义注解？
谁说生成接口请求和返回示例必须要在线？

用代码去探路，不断尝试更多文档交付的可能性。
如果代码有生命，为什么不换种方式和它对话！


一、背景

没有背景、就自己做自己的背景

在当今各种盛行的前后端分离、restful service开发过程中，接口文档是必不
可少的。对于前后端分离的开发中，后端开发需要将接口写好后需要告诉前端工程师接口的请求参数、响应示例等重要信息，而对于对外暴露的restful接口服务，我们提供接口也是需要具备相同的接口文档的。

但是对于后端工程师来讲，写接口文档将变成一个很大的工作量，虽然现在有类似apidoc、swagger这样的主流接口文档生成工具，但是如果实际用过，会发现这些工具不能满足实际需求，这里拿swagger为例，这个工具最大的优点能是提供在线的api文档，但是它天生就有很强的代码侵入性，要得到一个基本满足需求的api接口文档，必须在代码中使用swagger自定义的注解。这其实给开发人员增加学习成本和工作量，并且就算你使用大量的注解，有许多接口还是无法满足。因此不得不去做一次接口文档工具重新启航探索，smart-doc应允而生，用代码去探路，消除繁杂的注解，发现天下没有难写接口文档。


二、smart-doc简介

简约而不简单

smart-doc是基于java开发用于解决java web restful接口文档书写难和生成难的问题，当然api-doc也是一款零注解完全基于源代码接口定义，使用java标准注释生成接口文档的工具。并且smart-doc代码也是完全开源的。目前生成的文档格式为markdown。

api-doc的码云仓库链接

github仓库地址链接


三、功能特性

一个都不能少
  • 零注解、零学习成本、只需要写标准java注释。
  • 基于源代码接口定义自动推导
  • 支持springmvc、springboot
  • 目前支持javabean上定义的部分fastjson和jackson注解
  • 支持javabean上基于jsr303参数检验判断参数是否为必须
  • 对json请求参数的接口能够自动生成模拟json参数
  • 对一些常用字段定义能够生成有效的模拟值
  • 支持生成json返回值示例
  • 支持从项目外部加载源代码来生成字段注释
  • 一款代码注解检测工具，明眼leader都知道接口文档直接反馈出注释情况
  • 支持将错误码列表和全接口生成合并到一个markdown中 四、效率成效
效率是做好工作的灵魂。——切斯特菲尔德
  • 直接生成模拟请求参数，提升了团队里的前端和测试的工作效率，试想你让他们去编写json请求参数，如果你不写，鬼知道是什么样。
  • 后端开发只需专注业务和写好标准注释，无需引入额外注解，无需自己编写请求参数示例和响应示例。
  • 接口文档更加标准化 五、缺点
只有看到自己的不足，才能获得进步。
  • 由于基于源代码分析生成文档，因此无法生成在线文档，需要结合地方markdown文档管理工具来管理。
  • 由于源代码分析难度很大，针对很多代码存在潜在的大量的bug.
  • 对泛型返回接口需要明确定义泛型定义，否则无法推导 六、用例
<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>api-doc</artifactId>
    <version>0.5</version>
</dependency>


6.1 定义bean

/**
 * @author yu 2018/8/4.
 */
public class SimpleUser {

    /**
     * 用户名
     */
    @NotNull
    private String username;

    /**
     * 密码
     */
    private String password;

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

    /**
     * 电话
     */
    private String mobile;

}


6.2 定义接口

/**
 * 用户信息操作接口
 * @author yu 2018/8/4.
 */

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

    /**
     * 添加用户
     * @param user
     * @return
     */
    @PostMapping("/add")
    public List<SimpleUser> addUser(@RequestBody SimpleUser user){
        return null;
    }
}

启动文档生成

 /**
 * 包括设置请求头，缺失注释的字段批量在文档生成期使用定义好的注释
 */
@Test
public void testBuilderControllersApi() {
    ApiConfig config = new ApiConfig();
    config.setServerUrl("http://localhost:8080");
    config.setStrict(true);
    config.setOutPath("d:\\md");
    //不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
    config.setSourcePaths(
            SourcePath.path().setDesc("本项目代码").setPath("src/main/java")

           //  SourcePath.path().setPath("E:\\Test\\Mybatis-PageHelper-master\\src\\main\\java"),
           // SourcePath.path().setDesc("加载项目外代码").setPath("E:\\ApplicationPower\\ApplicationPower\\Common-util\\src\\main\\java")
    );

    long start = System.currentTimeMillis();
    ApiDocBuilder.builderControllersApi(config);
    long end = System.currentTimeMillis();
    DateTimeUtil.printRunTime(end, start);
}

生成文档


添加用户

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

Type: post

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

Request-parameters:

ParameterTypeDescriptionRequired
usernamestring用户名true
passwordstring密码false
nickNamestring昵称false
mobilestring电话false

Request-example:

{
    "username":"瑞霖.张",
    "password":"xud2qc",
    "nickName":"rudy.goyette",
    "mobile":"15650966307"
}

Response-fields:

FieldTypeDescription
usernamestring用户名
passwordstring密码
nickNamestring昵称
mobilestring电话

Response-example:

[
    {
        "username":"浩然.阎",
        "password":"dzlv56",
        "nickName":"kieran.herzog",
        "mobile":"17863739656"
    }
]

demo地址：https://github.com/shalousun/api-doc-test


七、未来定义

期待下一次我们更好的相遇
  • 修改源代码解析的众多的bug
  • 收集使用者的建议，提供非json请求参数的请求示例
  • 收集使用者一些新增功能建议，增加一些必须功能。


八、使用协议

尊重别人，才能让人尊敬。——笛卡尔
  • 任何企业和个人不得用于申请专利


九、使用反馈

分享是一种生活的信念，明白了分享的同时，明白了存在的意义。

smart-doc的发展离不开你的支持，因为出于完全的开源免费，因此您可以基于smart-doc的源码解析核心上去做一些自定义的开发来将接口文档数据接入到一些第三方的在线api文档管理系统，例如：CrapApi，但是在请使用者能有一份开源的心态和情怀，积极反馈api-doc的核心代码使用bug和提出改善意见。<br/>
由于我个人的开发精力有限，对于是否会将smart-doc快速集成推送到第三方优秀的管理工具，短期内可能不会考虑，因此也希望使用者分享一些比较好的集成方案来供大家使用，如果方案比较符合smart-doc使用简洁的核心理念，将会直接纳入后续的版本升级中，同时源代码和方案提供者也将纳入smart-doc的开发者。


十、祝福

愿你编写接口无数，归来仍是少年
点赞