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

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

上图是我生成的文件。

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

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

上图是安卓实体。

上图是ios实体。

下面我来说说如何操作。

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

<dependency>
   <groupId>io.github.yedaxia</groupId>
   <artifactId>japidocs</artifactId>
   <version>1.4</version>
</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 Res<UseVo> add(@RequestBody Use user){
        Res<UseVo> result = new Res<>();
        return result;
    }

    /**
     * 查询用户列表
     * @param uid 用户id
     * @param name 用户名
     * @Author : pipi.dan
     * @Date : 2021/1/23 9:53
     */
    @GetMapping("query")
    public Res<List<UseVo>> query(Long uid, String name){
        Res<List<UseVo>> result = new Res<>();
        return result;
    }
}

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

Res<T>

package com.example.xiaowu.domain;
import lombok.Data;
/**
 * @program: danpipi
 * @description: 返回
 * @author: Wu
 * @create: 2021-01-22 11:47
 **/
@Data
public class Res<T> {
    private int code;
    private boolean status;
    private String msg;
    private T data;
}

Use

package com.example.xiaowu.domain;
import lombok.Data;
@Data
public class Use {
    /**
     * 用户Id
     */
    private Long uid;
    /**
     * 用户名
     */
    private String name;
}

UseVo

package com.example.xiaowu.domain.requestVO;
import com.example.xiaowu.domain.Use;
import lombok.Data;
@Data
public class UseVo extends Use {
    /**
     * 用户信息
     */
    private String info;
}

写一个配置文件，随便写哪里都行，然后写个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接口文档已经生成了，是不是很简单快捷呢？