44

GitHub - apiggs/apiggs: 一个非侵入的RestDoc文档生成工具。工具通过分析代码和注释...

 5 years ago
source link: https://github.com/apiggs/apiggs
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.

README.md

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

Download

前言

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

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

代码即文档

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

引入插件

有这样一段代码

/**
 * 欢迎使用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 运行 task:
Tasks/documentation/apiggs
  • maven 运行
compile

生成文档

在编译目录下生成apiggs文件夹，并生成三个文件：

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

example

想了解更多，请查看Wiki

Versions

1.1

  • 增加注释Tag @return的支持，只支持类的全限定名
  • 插件支持子项目解析

1.0

  • 解析spring mvc源代码，构建Restful Api树
  • 生成postman v2.1格式的json文件
  • 生成Asciidoc文件
  • 渲染Asciidoc文件，生成html文件
  • 支持泛型的参数
  • 自定义注释Tag @index，定义文档顺序

report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK