生成api接口文档的故事

序
最近在整理优化项目，因为历史原因欠下很多接口文档的账，postman的导出json已不能满足测试、交付验收的要求，要写文档，对于写不爱写文档的人来说，简直是灾难。于是就开始了生成api接口文档的探索之路。主要也是试验了3种方式，javaDoc注释，直接使用idea的工具生成接口报告，出来的是html的，类似jdk的api，还是吃藕啊。下面主要说说2种方式，以及遇到的问题。
方式一：smartDoc
1、jar引入

<dependency><groupId>com.github.shalousun</groupId><artifactId>smart-doc</artifactId><version>1.9.9.1</version>
</dependency>

2、生成文档的测试类

@Slf4j
public class SmartDocTest {/*** 生成api接口文档* 功能看起来很强大，配置也相对而言繁琐，不过繁琐的匹配中生成的文档也好看，比如可以设置头文件与请求参数* 有maven插件、有jar，但是最终都报一个错误* com.thoughtworks.qdox.parser.ParseException: syntax error @[20,63] in file:/E:/Workspaces/intellij%20idea/oldTg/xxx/constant/DeviceDataExpressionEnum.java* 怀疑是不支持枚举里嵌套ImmutableMap，* 没有找到作者联系方式，在github上提了issues*/@Testpublic void testBuilderControllersApi() {ApiConfig config = new ApiConfig();config.setStrict(false);config.setAllInOne(true);//true则将所有接口合并到一个AllInOne中markdown中，错误码合并到最后config.setOutPath("d:\\md");ApiDocBuilder.buildApiDoc(config);}
}

这个插件还有maven打包插件，不过我不喜欢那种插件方式，毕竟现网不需要这一块插件。用这个测试类生成多好，不影响配置，不知道官方为什么不推荐，可能官方不满足作为一个jar包吧，哈哈。遇到不支持枚举嵌套ImmutableMap，提了issues，响应还挺快，今天（第二天）就收到了邮件回复：

继续反馈插件方式我也试过，看还有没有回复吧。
那么到此，此路我肯定是不适用了，如果大家没有我这样的问题，可以试试。
二、方式二：jApiDocs
1、jar引入

<!-- japidocs生成api接口文档支持 -->
<dependency><groupId>io.github.yedaxia</groupId><artifactId>japidocs</artifactId><version>1.4.4</version></dependency>

2、测试类

@Slf4j
public class JapiDocTest {/*** 生成apiDoc文档** 测试不支持JSONObject、map作为入参，已加作者微信、并发送邮件，等待回复*/@Testpublic void testBuilderApiDoc() {DocsConfig config = new DocsConfig();config.setProjectPath("E:\\Workspaces\\intellij idea\\oldTg\\ITSS"); // 项目根目录config.setProjectName("ITSS运维"); // 项目名称config.setApiVersion("V1.0");       // 声明该API的版本config.setDocsPath("d:\\md2"); // 生成API 文档所在目录config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成//config.addPlugin(new MarkdownDocPlugin());  //markdownDoc文档//config.setResourcePath("模板路径"); //模板路径替换位新的路径config.addPlugin(new CustomPlugin()); //自定义插件，没有可以不设置Docs.buildHtmlDocs(config); // 执行生成文档}
}

3、遇到的问题

警告: warning!! Cannot find java file , in java file : E:\Workspaces\intellij idea\oldTg\ITSS\src\main\java\com\easylinkin\bm\model\DeviceInfo.java, className : JSONObject, we cannot found more information of it, you've better to make it a JavaBeanjava.lang.ClassCastException: com.github.javaparser.ast.type.WildcardType cannot be cast to com.github.javaparser.ast.type.ClassOrInterfaceType

原因：后来断点进去看了，原因是我的controller入参有用map作为入参对象的，也是在作者的wiki上找到联系方式，加了微信，回复也很迅速：

也进了使用反馈群：

到此，这条路也不通了。所以大家在做传参时还是不要用map、jsonObject这种不能具体知道字段的对象，虽然扩展方便，但是你看，现在头疼了吧。所以说面向对象这个理念还是永恒的，现在其实遇到表结构要改也是很头疼的额，很多当时说不会存在1对多，多对多，所以就直接冗余了字段，没有用关系表，现在改起来也特费劲。所以说还是应该对象就是对象，关系就是关系。
对了这个还同时支持自定义的@apidoc标签描述接口的
注意以上2种方式时都需要写代码有最低的底线，有javadoc注释的，如果没有这个底线，那就不要谈了。工作这么多年，我时最讨厌不写注释的，不知道觉得时太简单都能看懂，还是说怕别人看懂。我一直就觉得，内部可以没有一行注释，但是方法上必须有。

三、疑问
也许会有小伙伴问我，怎么不用可以在线就能看到的Swagger UI，这个对代码有侵入性，方法上面要加一大串注释，非我所愿意，我也怕麻烦，哈哈。写个javadoc注释是底线。
好了就分享到这里吧，大家也可以找找，还有其他好多工具。我也再看看，实在不行，我就后面自己解析postman的请求示例json串，生成文档，再然后就是让解析的这些可以在线访问，免得测试、前端老问。敬请期待吧。

生成api接口文档的故事相关推荐

开发日记-20190328 关键词利用eolinker一键快速生成API接口文档
今天感觉效率真的很低= =各个层面的,apk发布到现场发现出现了问题,所以一个下午都在忙着解决现场出现的问题,领导一直打电话询问进度,午觉也没有睡所以今天预计的很多计划都处于停滞状态,像昨天规划的今天 ...
python生成api文档_Django 自动生成api接口文档教程
最近在写测试平台,需要实现一个节点服务器的api,正好在用django,准备使用djangorestframework插件实现. 需求实现一个接口,在调用时,通过传递的参数,直接运行对应项目的自动化 ...
python api接口生成_Django 自动生成api接口文档教程
最近在写测试平台,需要实现一个节点服务器的api,正好在用django,准备使用djangorestframework插件实现. 需求实现一个接口,在调用时,通过传递的参数,直接运行对应项目的自动化 ...
apidoc 自动化生成 api接口文档
手写api接口太麻烦. 学习了apidoc自动生成接口文档,这边做一下整理要用组件那就必须先安装 apidoc,做一下全局安装 npm install apidoc -g 新建配置文件apidoc. ...
Laravel使用swagger PHP生成api接口文档
Laravel使用swagger PHP生成api接口文档 Swagger集接口文档和测试于一体,就类比将postman和showdoc的结合体首先要先安装基于laravel5的swagger包地 ...
Laravel使用Apidoc注解自动生成Api接口文档
本教程从零开始搭建laravel项目,并安装Apidoc扩展及使用注解生成Api接口文档的教程,该扩展支持多应用/版本.Markdown文档.在线接口调试.接口生成器.代码模板生成器.Mock调试数 ...
如何自动生成 API 接口文档 - 一份详细指南
本篇文章详细教你如何使用 Apifox 的 IDEA 插件实现自动生成接口代码.好处简单总结有以下几点: 自动生成接口文档: 不用手写,一键点击就可以自动生成文档,当有更新时,点击一下就可以自动同步接 ...
springboot（05）整合 Swagger3 生成 API 接口文档
Spring Boot 集成 Swagger3 Swagger是一种开源的API文档工具,它可以自动生成RESTful API文档,让开发者可以更容易地理解和使用API.使用Swagger可以提高开发 ...
项目配置Swagger2生成API接口文档
一.Swagger2介绍前后端分离开发模式中,api文档是最好的沟通方式. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务. 及时性 (接 ...
coreapi自动生成API接口文档
文章目录 1 安装: 2 在路由中配置视图中使用方法 1 安装: pip install coreapi 2 在路由中配置 from rest_framework.documentation imp ...

生成api接口文档的故事

生成api接口文档的故事相关推荐

最新文章

热门文章