抛弃swagger,不写注解生成接口文档

之前用的swagger,必须要写注解才能在swagger文档中显示,测试起来也很方便,JAPIDOCS自动生成接口文档,不需要写任何注解,可以生成html形式的文档,还能生成docx格式的文档,我试了下,确实挺方便。

上图是我生成的文件。

这是生成的接口文档页面,包含controller中的方法。

参数,实体一目了然。还能生成安卓和ios的实体,前端开发可以直接复制粘贴走,省事很多。

上图是安卓实体。

上图是ios实体。

下面我来说说如何操作。

首先常规的添加依赖,这个项目在github上,可以把源码荡下来瞅瞅,改改上传到自己的maven私服,据为已有。

  <groupId>io.github.yedaxia

  <artifactId>japidocs

  <version>1.4

</dependency>

虽然说该文档不需要写任何注解,但是要遵循一定的规范,不然这些文档咋能生成呢?下面我写了个demoController,以下粘贴出来代码。

package com.example.xiaowu.controller;

import com.example.xiaowu.domain.Res;

import com.example.xiaowu.domain.Use;

import com.example.xiaowu.domain.requestVO.UseVo;

import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController

@RequestMapping("demo/user")

public class DemoController {

/**

    * 新增用户

    * @param user

    * @Author : pipi.dan

    * @Date : 2021/1/23 9:53

*/

    @PostMapping("add")

public Resadd(@RequestBody Use user){

Res result =new Res<>();

        return result;

    }

/**

    * 查询用户列表

    * @param uid 用户id

    * @param name 用户名

    * @Author : pipi.dan

    * @Date : 2021/1/23 9:53

*/

    @GetMapping("query")

public Res>query(Long uid, String name){

Res> result =new Res<>();

        return result;

    }

}

我写了一个返回实体和两个入参实体。

Res

package com.example.xiaowu.domain;

import lombok.Data;

/**

* @program: danpipi

* @description: 返回

* @author: Wu

* @create: 2021-01-22 11:47

**/

@Data

public class Res {

private int code;

    private boolean status;

    private Stringmsg;

    private T data;

}

Use

package com.example.xiaowu.domain;

import lombok.Data;

@Data

public class Use {

/**

    * 用户Id

*/

    private Longuid;

    /**

    * 用户名

    */

    private Stringname;

}

UseVo

package com.example.xiaowu.domain.requestVO;

import com.example.xiaowu.domain.Use;

import lombok.Data;

@Data

public class UseVoextends Use {

/**

    * 用户信息

    */

    private Stringinfo;

}

写一个配置文件,随便写哪里都行,然后写个main方法,我是为了规范跟我的配置文件写一起了。

main方法内容如下:

package com.example.xiaowu.config;

import io.github.yedaxia.apidocs.Docs;

import io.github.yedaxia.apidocs.DocsConfig;

import io.github.yedaxia.apidocs.plugin.markdown.MarkdownDocPlugin;

/**

* @program: xiaowu

* @description: JapiDoc

* @author: Wu

* @create: 2021-01-22 11:41

**/

public class CreateJapiDocsConfig {

public static void main(String[] args) {

DocsConfig config =new DocsConfig();

        // 项目根目录

        config.setProjectPath("D:\\ideaworkspace\\house");

        // 项目名称

        config.setProjectName("house");

        // 声明该API的版本

        config.setApiVersion("V1.0");

        // 生成API 文档所在目录

        config.setDocsPath("D:\\api");

        // 配置自动生成

        config.setAutoGenerate(Boolean.TRUE);

        //添加生成doc文档的文档

        config.addPlugin(new MarkdownDocPlugin());

        // 执行生成文档

        Docs.buildHtmlDocs(config);

    }

}

单机运行此方法就可以生成html文档。

但是想要docx文档,我们需要安装一下pandoc插件,下载地址在

https://github.com/jgm/pandoc/releases/tag/2.10.1,找到msi格式的下载下来安装到电脑上后,执行如下命令可以将生成的md文件转化成docx接口文档。

pandoc -s docs.md -o docs.docx

在你的工作空间那里cmd执行

docx接口文档已经生成了,是不是很简单快捷呢?

喜欢请关注“蛋皮皮”微信公众号!

推荐阅读更多精彩内容