Jboot v3.10.0 发布,带来市面上最好用的 api 文档工具

来源: 投稿
作者: 开源海哥
2021-06-29

Jboot 一个更简单的分布式、微服务框架。

Jboot是一个基于 JFinal、JFinal-Undertow、Dubbo、Seata、Sentinel、ShardingSphere、Nacos 等开发的微服务框架,帮助开发者降低微服务、分布式开发门槛。爽爽开发,快乐生活。

到目前为止,Jboot 已经开源超过了 5 年的时间,迭代了 200+ 个版本,已经被超过 1000+ 公司在使用,其中包含了多个知名的上市公司,我们了解到的多个使用 Jboot 开发的产品,用户量超过 1亿 以上。

Jboot v3.10.0 的发布,主要是带来了自研的 API 文档生成工具。

目前市面上的 API 文档工具生成,有非常多的弊端,就拿大名鼎鼎的 Swagger 对比 Jboot 而言。

缺点1:大量的繁杂注解,而 Jboot 只有 3 个,比如:

Swagger:

@ApiOperation(value="更新用户详细信息", notes="...")
@ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
@RequestMapping(value="/{id}", method=RequestMethod.PUT)
public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
}    

Jboot:

@ApiOper(value="更新用户详细信息", notes="...")
public String putUser(@ApiPara('用户ID')Long id, @ApiPara('用户详细实体use')@JsonBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
}    

缺点2:Swagger 无法自动推导参数类型,而 Jboot 可以自动推导更加智能。

Jboot:

@ApiOper(value="更新用户详细信息", notes="...")
public String putUser(@Min(1) Long id, @NotNull @JsonBody User user) {
  ...
}    

在 Jboot 中,有很多的验证注解,比如 @Email、@NotNull、@Min、@NotEmpty... 等等注解会自动推导并放到文档(或者测试前端)进行显示或自动验证。

除了这些验证注解以外,Java 类型,返回参数等等都可以智能的进行自动推导。

缺点3:Swagger 只能通过其前端进行查看文档或进行测试验证。而 Jboot 可以扩展适配任何的测试框架,比如  Postman、OpenAPI 等等... 又可以生成 Markdown 文档、Html、Word 等等类型文档。

比如,以下是 Jboot 自动生成的 JPress API 文档。

总而言之:Swagger 需要繁杂的注解,无法自动推导,而个别带有推导功能的,又无法准确推导 API 验证等信息,无法准确的为 API 进行配置,相对市面上所有的 API 文档框架,Jboot 应该是最好用的。

Jboot v3.10.0 更新内容如下:

  • 新增:apidoc 模块
  • 优化:JbootCaptchaCache 在某些情况下可能出现错误的问题
  • 优化:升级 JFinal 到 v4.9.14 最新版本

 

Jboot 开发文档:

http://www.jboot.io

同时,Jboot 官方也推出了收费的、企业级快速开发框架 JbootAdmin (如下图所示),真诚的为各位开发者提供一站式、保姆式服务。请咨询海哥。

Maven 依赖:

<dependency>
    <groupId>io.jboot</groupId>
    <artifactId>jboot</artifactId>
    <version>3.10.0</version>
</dependency>

Hello World:

@RequestMapping("/")
public class HelloWorld extends JbootController {

    public void index(){
        renderText("hello world");
    }

    public static void main(String[] args){
        JbootApplication.run(args);
    }
}
展开阅读全文
15 收藏
分享
加载中
最新评论 (7)
加注解生成文档,侵入性大,是最差的文档生成方式,已经有比你这个更好的不需要注解生成文档工具了
2021-06-30 18:15
0
回复
举报
Yapi + IDEA插件EasyYapi,可以实现代码零侵入生成文档。
2021-06-30 10:35
0
回复
举报
目前市面上的 API 文档工具生成,有非常多的弊端。生产模式后门漏洞必备
2021-06-29 11:05
0
回复
举报
文档工具有独立jar包吗 哈哈
2021-06-29 10:18
0
回复
举报
内置在 Jboot 里了
2021-06-29 10:47
0
回复
举报
内置在 jboot 里了
2021-06-29 11:26
0
回复
举报
厉害了,我的海哥
2021-06-29 10:10
0
回复
举报
更多评论
7 评论
15 收藏
分享
返回顶部
顶部