「掘金者说」不穿丝袜哥(swagger),也能提供API接口文档

3,283 阅读2分钟

掘金者说,上回用注解代替if-else,让代码更优雅!创建了一个新的工程pig-strategy进行讲述策略模式,添加注解开发。

《三十而已》两个人职位没有什么不同,都不具备不可替代性,就像马路上跑过的这些汽车,看似都有一个车牌,但是如果你不去挣油费,连上路的资格都没有。

在此,只是做个实践操作记录,具体细节参考官方文档

后来想注解少写点了可以吗?我们经常使用的接口文档swagger-ui 谐音“丝袜哥”,每次添加swagger都要添加maven依赖、添加config配置、添加@API实体类引入、控制器上面添加。如果我们想省时又省事儿,那么我们就找到了无侵入式的开源小架子,解开我们的燃眉之急。

JApiDocs是一个无需额外注解、开箱即用的 SpringBoot API文档生成工具。 我们编写和维护API文档这个事情,对于后端程序员来说,API文档将是前后端协作中一个不可或缺的沟通界面。既然不可避免,那就想办法解决。

实践操作

第一步:添加依赖

<dependency>
  <groupId>io.github.yedaxia</groupId>
  <artifactId>japidocs</artifactId>
  <version>1.4.2</version>
</dependency>

第二步:配置参数

你可以在任意一个main入口运行下面的代码:

    @Test
    void test_japidocs() {
        DocsConfig config = new DocsConfig();
        // 项目根目录
        config.setProjectPath("E:\\pig-study\\pig-strategy");
        // 项目名称
        config.setProjectName("pig-strategy");
        // 声明该API的版本
        config.setApiVersion("V1.0");
        // 生成API 文档所在目录
        config.setDocsPath("E:\\pig-study\\pig-strategy\\japidocs");
        // 配置自动生成
        config.setAutoGenerate(Boolean.TRUE);
        // 添加插件(MarkdownDoc)
        config.addPlugin(new MarkdownDocPlugin());
        // 执行生成文档
        Docs.buildHtmlDocs(config);

    }

如果没有意外,执行完上面的代码后,你就可以在配置的目录中看到生成的文档了。

异常VoidType

java.lang.ClassCastException: com.github.javaparser.ast.type.VoidType cannot be cast to com.github.javaparser.ast.type.ClassOrInterfaceType
  • 问题解决:

这是由于接口方法没有声明返回参数导致的(void),理论上请求应该都有返回值。如果没有通过return type来声明的,可以通过@ApiDoc来指定返回类型。issues80

例子: 原先的代码添加 @ApiDoc(Result.class)

    /**
     * 获取图片
     */
    @ApiDoc(Result.class)
    @GetMapping("get-image")
    public void getImage() {

    }

实践效果

  • html

  • markdown

总之,注解还是要写的,仅仅几个注解搭配即可。实践操作,体验一下。

参考资料

pig4cloud :pig4cloud.com/

官方文档:japidocs.agilestudio.cn/#/zh-cn/?id…

仓库地址:github.com/YeDaxia/JAp…

中文文档:japidocs.agilestudio.cn/#/zh-cn/

资料地址:mp.weixin.qq.com/s/HRGREstzN…