所有分类
  • 所有分类
  • 未分类

JavaWeb–接口文档工具

本系列介绍常用的接口文档工具以及自学精灵推荐使用的工具。使用了好的接口文档工具可以事半功倍,提高调试速度。

自学精灵推荐使用Knife4j(Wwagger的升级版),项目里的示例也都是使用Knife4j来测试。使用Knife4j时,直接使用Swagger的注解即可。

实战

Knife4j-使用/教程/实例 – 自学精灵

Swagger-使用/教程/实例/配置 – 自学精灵

Swagger-注解大全 – 自学精灵

Knife4j-将接口信息同步到Yapi – 自学精灵

接口文档工具选型

一个好的接口文档具有如下特点:

  1. 开源。
  2. 能实时生成在线文档(通过正在运行的项目直接导出)。
  3. 支持全文搜索。
  4. 支持在线调试。
  5. 界面优美。

自学精灵认为:有一个特性很重要,就是要通过注解生成接口文档,不能是注释。原因是:

  1. 使用注解可以在运行时获取信息,从而可以自动生成日志。
  2. 如果提供给别人使用(比如:feign接口的入参),注解内容依然存在,但注释却没有了。

有人这样认为:接口文档的注解对代码有干涉,不建议用注解。自学精灵认为:接口文档是相当重要的,加个注解利远大于弊。

自学精灵推荐的工具,由好到坏依次是:

  • knife4j
  • yapi
  • apidoc
  • showdoc

knife4j

gitee地址:https://gitee.com/xiaoym/knife4j

推荐指数:★★★★★

优点

基于swagger生成实时在线文档,支持在线调试,全局参数、国际化、访问权限控制等,功能非常强大。

缺点

界面不是特别出彩。

图片展示

yapi

github地址:https://github.com/YMFE/yapi

推荐指数:★★★★

优点

功能强大,支持权限管理、在线调试、接口自动化测试、插件开发等,BAT等大厂等在使用。

缺点

  1. 默认没有在线调试功能。(需要安装插件,用户体验不好)。
  2. 搜索功能难用

apidoc

介绍

基于代码注释生成在线文档。

github地址:https://github.com/apidoc/apidoc

推荐指数:★★★

示例地址:https://apidocjs.com/example/#api-User

优点

支持多种语言,跨平台,也可自定义模板。支持搜索和在线调试功能。

缺点

需要在注释中增加指定注解,如果代码参数或类型有修改,需要同步修改注释相关内容,有一定的维护工作量。

showdoc

github地址:https://github.com/star7th/showdoc

推荐指数:★★

优点

支持项目权限管理,多种格式文件导入,全文搜索等功能,使用起来还是非常方便的。并且既支持部署自己的服务器,也支持在线托管两种方式。

缺点

要手写文档,无法自动生成
在线调试只支持get和post

示例地址:https://www.showdoc.com.cn/demo?page_id=9

0

评论0

请先

显示验证码
没有账号?注册  忘记密码?

社交账号快速登录