apigcc / apigcc Goto Github PK

View Code? Open in Web Editor NEW

215.0 14.0 58.0 686 KB

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

Home Page: http://www.apigcc.com

License: MIT License

Java 99.55% HTML 0.45%

java api restdoc generator

apigcc's Introduction

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

前言

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

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

代码即文档

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

有这样一段代码

/**
 * 欢迎使用Apigcc
 * @index 1
 */
@RestController
public class HelloController {

    /**
     * 示例接口
     * @param name 名称
     * @return
     */
    @RequestMapping("/greeting")
    public HelloDTO greeting(@RequestParam(defaultValue="apigcc") String name) {
        return new HelloDTO("hello "+name);
    }

}

生成文档效果

使用方式

Hub

Gradle插件

Maven插件

apigcc's People

Contributors

Stargazers

Watchers

apigcc's Issues

java.nio.file.InvalidPathException: Illegal char <*>

用自己项目生成的时候，报了下面这个错，但是没有这样的java文件
Caused by: java.nio.file.InvalidPathException: Illegal char <*> at index 64: D:\workspace\trade-impl\src\main\java/******************************************************************.java at sun.nio.fs.WindowsPathParser.normalize(WindowsPathParser.java:182) at sun.nio.fs.WindowsPathParser.parse(WindowsPathParser.java:153) at sun.nio.fs.WindowsPathParser.parse(WindowsPathParser.java:77) at sun.nio.fs.WindowsPath.parse(WindowsPath.java:94) at sun.nio.fs.WindowsFileSystem.getPath(WindowsFileSystem.java:255) at java.nio.file.Paths.get(Paths.java:84) at com.github.javaparser.symbolsolver.resolution.typesolvers.JavaParserTypeSolver.tryToSolveTypeUncached(JavaParserTypeSolver.java:204) at com.github.javaparser.symbolsolver.resolution.typesolvers.JavaParserTypeSolver.lambda$tryToSolveType$4(JavaParserTypeSolver.java:173) at com.google.common.cache.LocalCache$LocalManualCache$1.load(LocalCache.java:4904) at com.google.common.cache.LocalCache$LoadingValueReference.loadFuture(LocalCache.java:3628) at com.google.common.cache.LocalCache$Segment.loadSync(LocalCache.java:2336) at com.google.common.cache.LocalCache$Segment.lockedGetOrLoad(LocalCache.java:2295) at com.google.common.cache.LocalCache$Segment.get(LocalCache.java:2208) ... 51 more

asiidoc的关键字与注释模板冲突

比如在asiidoc中

*****************
aaaaaaaa
*****************
bbbbbbbb
*****************

这样的注释模板就是乱掉，可能需要转义一下，今天白天我也稍微看一下。
可以通过

++++
*****************
++++

这样的方式解决，不知道还有没有更优雅的方式，我不太懂asiidoc的规范

扫描到非 API 接口的 Controller

hi，非常感谢作者提供这款工具，使用非常方便，也省去很多与移动端沟通的时间。作为一个非侵入式框架能够达到这样的效果已经非常不错了
使用之后发现有个问题，项目中接口和后台是整合在一起的，所有有些 Controller 用于处理后台的业务逻辑，而生成的接口文档会将所有的 Controller 中的方法全部扫描出来
是否可以增加配置项，来指定生成某些规则的 Controller
例如 RequestMapping 以 api 开头的 Controller 才是需要生成的接口
那在插件中使用自定义配置 api/** 类似的效果，希望作者考虑

项目很nick，可以加一个mock库来mock数据，解决泛型mock的问题

mock 库地址
mock 我测试过了，这种模式是没有问题的，我在公司内部验证http调用dubbo，跟你这个异曲同工 👍 :)

是否必填信息无法体现

例如：@RequestParam(required = false)在文档中无法表现

controller 判断问题

controller 声明还有一种方式，只在类上声明@RequestMapping 再用configuration+@bean 的方式声明bean 不会被扫描到。请修改下springparser

泛型问题

无法解析泛型的对象

name属性无法解析

@RequestParam(name="user_name")

只能读value="user_name",不能读name

依赖jar包中的response对象不能生成返回信息，如何配置maven插件？

入参和返回值的解析不全

入参：正常类Class或者枚举Enum，解析不完全，会漏掉
返回值：在class中嵌套list中嵌套list就解析不完全了
version 1.6.3-SNAPSHOT

希望增加生成markdown功能

希望添加生成markdown支持

如何确定response status？

例如一个PUT方法，response body没有内容，我打算响应204，但文档中却并没有生成该说明，应该用什么参数来进行配置呢？

源码与 Maven 仓库中 jar 不匹配

建议在开发新功能时可以建立分支，主干保持与 Maven **仓库版本一致

gradle plugins搜索不到

https://plugins.gradle.org/

接口响应接口怎么展示

提两个问题

1、加了 @return 类名之后windows系统会打包报错，mac系统正常，看报错内容可能是文件系统分隔符差异所致
2、返回值无法生成到文档中。直接返回具体类，或者返Object都不行

生成的文档入参未能解析

controller的方法为：

@RequestMapping(value = "/query")
public ResponseDataWrapper queryCustomer(@requestbody CustomerQueryParamDto param, HttpServletRequest request) {
}

生成的文档：

POST /wap/customer/query HTTP/1.1
Content-Type: application/json

文档中入参没了，类似的方法，没有HttpServletRequest request参数，解析没有问题

响应内容不显示

使用的maven插件，1.6的版本，文档生成成功了，但是只有请求内容，没有响应内容，返回使用的对象使用的demo中的HelloDto

显示 java.nio.file.InvalidPathException

[WARNING] The requested profile "test" could not be activated because it does not exist.
[ERROR] Failed to execute goal com.github.apiggs:apiggs-maven-plugin:1.6:apiggs (default) on project sofb-onlinemg: Execution default of goal com.github.apiggs:apiggs-maven-plugin:1.6:apiggs failed: java.nio.file.InvalidPathException: Illegal char <"> at index 50: D:\test\sofb-onlinemg\onlinemg-web\src\main\java/{"success":true,"code":"C0000","msg":"成功！","data":[{"id":1,"name":"本地楼市","level":1},{"id":4,"name":"房屋买卖","level":1}]}.java -> [Help 1]
[ERROR]

什么原因能造成没有返回结果

/**
* 通过用户id查询用户详情
* @param id 用户Id
* @return UserVO
*/
@PostMapping("find-user/{id}")
public UserVO findUserById(@PathVariable long id) {
UserVO userVO = new UserVO();
userVO.setId(id);
userVO.setAge(100);
return userVO;
}

UserVO 是使用lombok注解的

生成的结果没有返回结果，只显示请求参数