生成api接口文档的故事

80 阅读 0 评论 53 点赞

我是靠谱客的博主甜美发卡，最近开发中收集的这篇文章主要介绍生成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
     */
    @Test
    public 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作为入参，已加作者微信、并发送邮件，等待回复
     */
    @Test
    public 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:Workspacesintellij ideaoldTgITSSsrcmainjavacomeasylinkinbmmodelDeviceInfo.java, className : JSONObject, we cannot found more information of it, you've better to make it a JavaBean

java.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串，生成文档，再然后就是让解析的这些可以在线访问，免得测试、前端老问。敬请期待吧。