/apigcc

一个非侵入的api编译、收集、Rest文档生成工具。工具通过分析代码和注释,获取文档信息,生成RestDoc文档。

Primary LanguageJavaMIT LicenseMIT

🐷 Apiggs - 非侵入的RestDoc文档生成工具

Download

前言

程序员一直以来都有一个烦恼,只想写代码,不想写文档。代码就表达了我的**和灵魂。

Python提出了一个方案,叫docstring,来试图解决这个问题。即编写代码,同时也能写出文档,保持代码和文档的一致。docstring说白了就是一堆代码中的注释。Python的docstring可以通过help函数直接输出一份有格式的文档,本工具的**与此类似。

代码即文档

Apiggs是一个非侵入的RestDoc文档生成工具。工具通过分析代码和注释,获取文档信息,生成RestDoc文档。

引入插件

gradle

buildscript {
    dependencies {
        classpath 'com.github.apiggs:apiggs-gradle-plugin:替换为上方版本号'
    }
}

apply plugin: 'com.github.apiggs'

maven

<plugin>
    <groupId>com.github.apiggs</groupId>
    <artifactId>apiggs-maven-plugin</artifactId>
    <version><!-- 替换为上方版本号 --></version>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>apiggs</goal>
            </goals>
        </execution>
    </executions>
</plugin>

有这样一段代码

/**
 * 欢迎使用Apiggs
 * @index 1
 */
@RestController
public class GreetingController {

    private static final String template = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();

    /**
     * 示例接口
     * @param name 名称
     * @return
     */
    @RequestMapping("/greeting")
    public Greeting greeting(@RequestParam(value="name", defaultValue="apiggs") String name) {
        return new Greeting(counter.incrementAndGet(),
                String.format(template, name));
    }
}

运行插件

  • gradle 运行
Tasks/documentation/apiggs
  • maven 运行
compile

生成文档

在编译目录下生成apiggs文件夹,并生成三个文件:

  1. .json文件,可直接导入postman
  2. .adoc文件,Asciidoc源文件
  3. .html文件,源文件渲染结果,效果如下图

example

想了解更多,请查看Wiki