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

淩亂°似流年 2023-02-20 03:27 7阅读 0赞

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

自动本地静态资源：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw_size_16_color_FFFFFF_t_70][]

页面效果

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw_size_16_color_FFFFFF_t_70 1][]

通过Markdown和pandoc生成Word文档

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw_size_16_color_FFFFFF_t_70 2][]

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

结果：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw_size_16_color_FFFFFF_t_70 3][]

生成的Word

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw_size_16_color_FFFFFF_t_70 4][]

pandoc的下载路径：

[https://github.com/jgm/pandoc/releases/tag/2.9.2.1][https_github.com_jgm_pandoc_releases_tag_2.9.2.1]

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

文档路径：

[https://pandoc.org/installing.html][https_pandoc.org_installing.html]

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

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

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

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200623100741868.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200623102217303.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20200623112321932.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20200623112137414.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw_size_16_color_FFFFFF_t_70 4]: https://img-blog.csdnimg.cn/20200623112303820.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hlbGxvV29ybGRZYW5nU29uZw==,size_16,color_FFFFFF,t_70
[https_github.com_jgm_pandoc_releases_tag_2.9.2.1]: https://github.com/jgm/pandoc/releases/tag/2.9.2.1
[https_pandoc.org_installing.html]: https://pandoc.org/installing.html