Swagger（丝袜哥）他妹JapiDocs自动生成接口文档，真香

1. 话不多说，有图有真相，看看香不。

自动本地静态资源：

 

页面效果

 

通过Markdown和pandoc生成Word文档

2. 直接看代码

2.1 依赖

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

2.2 没有配置，就一个main函数，随便写在项目那里

package com.yarm.config;

import io.github.yedaxia.apidocs.Docs;
import io.github.yedaxia.apidocs.DocsConfig;

public class CreateJapiDocsConfig {
    public static void main(String[] args) {
        DocsConfig config = new DocsConfig();
        // 项目根目录
        config.setProjectPath("D:\\develop\\code\\java\\my_default\\java-share-base\\japi-docs");
        // 项目名称
        config.setProjectName("Springboot JapiDocs Demo");
        // 声明该API的版本
        config.setApiVersion("V1.0");
        // 生成API 文档所在目录
        config.setDocsPath("D:\\document\\japi_docs_demo");
        // 配置自动生成
        config.setAutoGenerate(Boolean.TRUE);
        // 执行生成文档
        Docs.buildHtmlDocs(config);
    }
}

其中，两个指定的路径注意一下即可，自己细品

2.3 简单解释一下用法

JApiDocs是通过解析Java源码来实现的，要使得JApiDocs正确工作，需要你在项目中的Controller书写遵循一定的编码规范。

如：

    /**
     * 删除用户
     * @param userId 用户ID
     */

其中，注释，会默认显示在文档中，@param表示对参数的解释，主要是入参的解释

2.4 写一个controller

2.4.1 定义统一的返回结果类

package com.yarm.pojo;

import lombok.Data;

@Data
public class Result<T> {
    private int code;
    private boolean status;
    private String msg;
    private T data;
}

这个不解释，自己细品

2.4.2 DemoController

定义的两个对象

User类

package com.yarm.pojo;

import lombok.Data;

@Data
public class User {
    /**
     * 用户Id
    */
    private Long uid;
    /**
     * 用户名
     */
    private String name;
}

UserVo类

package com.yarm.pojo;

import lombok.Data;

@Data
public class UserVo extends User {
    /**
     * 用户信息
     */
    private String info;
}

DemoController类

package com.yarm.controller;

import com.yarm.pojo.Result;
import com.yarm.pojo.User;
import com.yarm.pojo.UserVo;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("demo/user")
public class DemoController {
    /**
     * 新增用户
     * @param user
     * @Author : yarm.yang
     * @Date : 2020/6/23 9:53
    */
    @PostMapping("add")
    public Result<UserVo> add(@RequestBody User user){
        Result<UserVo> result = new Result<>();
        return result;
    }

    /**
     * 查询用户列表
     * @param uid 用户id
     * @param name 用户名
     * @Author : yarm.yang
     * @Date : 2020/6/23 9:53
     */
    @GetMapping("query")
    public Result<List<UserVo>> query(Long uid, String name){
        Result<List<UserVo>> result = new Result<>();
        return result;
    }
}

3. 重新执行刚才的main方法，即可重新生成最新的接口文档

4. 生成Word

main函数中加

config.addPlugin(new MarkdownDocPlugin());

通过pandoc生成

 pandoc -s docs.md -o docs.docx

结果：

 

生成的Word

pandoc的下载路径：

https://github.com/jgm/pandoc/releases/tag/2.9.2.1

记得配置pandoc的环境变量：path

文档路径：

https://pandoc.org/installing.html

用的爽的话，别忘了点赞哦。

仓库地址：https://github.com/YeDaxia/JApiDocs

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