听说丝袜哥(swagger)不好用试试JApiDocs吧

一介绍

JApiDocs 是一个符合 Java 编程习惯的 Api 文档生成工具。最大程度地利用 Java 的语法特性，你只管用心设计好接口，添加必要的注释，JApiDocs 会帮你导出一份漂亮的 Html 文档，并生成相关的 Java 和 Object-C 相关数据模型代码，从此，Android 和 IOS 的同学可以少敲很多代码了，你也不需要费力维护接口文档的变化，只需要维护好你的代码就可以了。

有人嫌弃使用Swagger 要使用很多注解， 当项目比较大时，光注解就需要写很多时间，然后 JApiDocs 完全可以使用Java原生的代码代替它；

官方 giee地址： https://gitee.com/yeguozhong/JApiDocs

二入门使用

2.1引入依赖

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

2.2 在VO上加上java注释

/**
 * @Author lsc
 * <p> 测试实体 </p>
 */
public class TestVo  {

    /** 测试名称**/
    private String testName;

    /** 测试年龄 **/
    private Long testAge;

    /** 测试时间 **/
    private LocalDateTime testTime;

    // 省略 set get
}

2.3 控制层加上java注释

/**
 * @Author lsc
 * <p>测试 </p>
 */
@RestController
public class TestController {

   /**
    * 测试get
    * @param testVo
    */
    @GetMapping(value = "info")
    public ResponseEntity<TestVo> testGet(TestVo testVo){
        return ResponseEntity.ok().body(testVo);
    }

    /**
     * 测试get参数
     * @param id
     */
    @GetMapping(value = "info/test")
    public ResponseEntity<Long> test(@RequestParam Long id){
        return ResponseEntity.ok().body(id);
    }

    /**
     * 测试post
     * @param testVo
     */
    @PostMapping(value = "info")
    public ResponseEntity<Long> testPost(@RequestBody TestVo testVo){
        return ResponseEntity.ok().body(1L);
    }

    /**
     * 测试delete
     * @param id
     */
    @DeleteMapping(value = "info/{id}")
    public ResponseEntity<Long> testPost(@PathVariable Long id){
        return ResponseEntity.ok().body(1L);
    }

}

2.4 生成文档

 public static void main(String[] args) {
        // 1. 创建生成文档的配置
        DocsConfig config = new DocsConfig();
        // 项目所在目录
        config.setProjectPath("C:/java/zszxz/studys-pringboot/springboot-JApiDocs");
        // 生成 HTML 接口文档的目标目录
        config.setDocsPath("C:/mydata/generator/japi");
        // 自动生成
        config.setAutoGenerate(Boolean.TRUE);
        // 项目名
        config.setProjectName("japi测试项目");
        // API 版本号
        config.setApiVersion("V1.0");
        // 使用 MD 插件，额外生成 MD 格式的接口文档
        config.addPlugin(new MarkdownDocPlugin());
        // 2. 执行生成 HTML 接口文档
        Docs.buildHtmlDocs(config);

    }

生成文档目录如下

访问 index 页面

三高级用法

高级用法基本我们都用不到，了解下；

3.1@ApiDoc

默认情况下，JApiDocs仅导出声明@ApiDoc的api。 我们之前通过设config.setAutoGenerate（Boolean.TRUE）删除了此限制。

如果不想导出所有api，则可以关闭autoGenerate并将@ApiDoc添加到Controller类或api方法中，以确定需要导出的api。

让我们看看@ApiDoc如何在api方法上工作：

result ：返回的对象类型，它将覆盖SpringBoot的返回对象
url：请求URL，扩展字段，用于支持非SpringBoot项目
method：请求方法，扩展字段，用于支持非SpringBoot项目

示例

@ApiDoc(result = AdminVO.class, url = "/api/v1/admin/login2", method = "post")

将 @ApiDoc 放在非springboot的项目上就是很好的选择

3.2 @Ignore

如果不想导出实体上的某个字段就可以使用@Ignore 注解

示例

public class TestVo  {

    /** 测试名称**/
    @Ignore
    private String testName;
}    

3.3 导出 Markdown

在配置时加上下面这行代码就可以生成 Markdown 文件

config.addPlugin(new MarkdownDocPlugin());

最后

关于本教程示例源码合并在 springboot 系列教程源码： https://github.com/zszxz/study-springboot

知识追寻者开源的权限管理系统: https://github.com/zszxz/zboot

希望大家多多支持，给个start！！

欢迎关注我的公众号：知识追寻者；