用JApiDocs代替Swagger生成接口文档

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

用JApiDocs代替Swagger生成接口文档

相比Swagger要写一堆注解,Spring RestDocs需要写测试用例,才能生成API文档。JApiDocs 具有无痛集成的特点,你只需花几分钟就能知道它怎么用了。

快速开始

要使得JApiDcos正确工作,你写的代码应该是像下面的样子的:

/**
 * 用户接口
 */
@RequestMapping("/api/user/")
@RestController
public class UserController {
    /**
     * 用户列表
     * @param listForm
     */
    @RequestMapping(path = "list", method = {RequestMethod.GET,  RequestMethod.POST}  )
    public ApiResult<PageResult<UserVO>> list(UserListForm listForm){
        return null;
    }

    /**
     * 保存用户
     * @param userForm
     */
    @PostMapping(path = "save")
    public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){
        return null;
    }
}

我们给Controller类和方法加上必要的注释,给接口方法返回相关的对象类型。是的,这样JApiDocs就能解析到相关的接口信息了,就跟我们平时写的代码是差不多的,但要注意,你要通过 @param 来告诉JApiDocs接口的参数,但在IDE的帮助下,这个工作将是轻松愉悦的:

用JApiDocs代替Swagger生成接口文档

然后你在任意一个 main 入口方法执行下面的代码就可以生成文档了

DocsConfig config = new DocsConfig();
config.setProjectPath("your springboot project path"); // 项目根目录
config.setProjectName("ProjectName"); // 项目名称
config.setApiVersion("V1.0");       // 声明该API的版本
config.setDocsPath("your api docs path"); // 生成API 文档所在目录
config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成
Docs.buildHtmlDocs(config); // 执行生成文档

接下来你只管好好写代码,生成Api文档的工作就可以交给JApiDocs了,你不需要再为额外编写和维护文档而烦恼。

功能特性

1、代码即文档JApiDocs是通过直接解析SpringBoot的源码语法来工作的,所以只要Controller的语法符合一定的代码规范,有合理的注释,就可以直接导出文档。 2、支持导出HTML 便捷的导航和接口查看界面;可本地预览,或者部署HTTP服务器。推荐部署到服务器,方便前后端展开协作。 3、同步导出客户端Model代码 支持导出Android端的 Java 和iOS端的 Object C Model代码,减少前端程序员的重复编码工作。 4、更多特性 支持接口搜索;支持不同版本和英文文档;自定义扩展等。

简洁的文档

再好用的东西,如果没有文档说明,别人也无从入手。为了让大家尽快上手,JApiDocs准备了一份极简的文档说明,确保你在几分钟就能用上JApiDocs。花5分钟不到就能认识一个提高工作效率的工具,让你把更多的时间花在更加有价值的事情上,你确认不看一下吗? 仓库地址:https://github.com/YeDaxia/JApiDocs 中文文档:https://japidocs.agilestudio.cn/#/zh-cn/

原文 

https://www.geek521.com/2020/07/13/用japidocs代替swagger生成接口文档/

本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。

PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处:Harries Blog™ » 用JApiDocs代替Swagger生成接口文档

赞 (0)
分享到:更多 ()

评论 0

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址