1 Star 0 Fork 129

cuiqunhao / JApiDocs

forked from 叶大侠 / JApiDocs 
加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
该仓库未声明开源许可证文件(LICENSE),使用请关注具体项目描述及其代码上游依赖。
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README

English ReadMe

简介

一个简单的示例

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

反馈交流Q群:70948803

特性

  1. 以一个 Controller 作为一组接口导出到一个 Html 文件中。
  2. 支持生成 Java 和 Object-C 语言的 Response 模型代码。
  3. 深度支持 Spring BootPlayFrameworkJFinal,不需要额外声明路由。
  4. 支持一般的 Java Web 工程,需要在相关方法添加额外的路由。
  5. 支持接口声明过时(@Deprecated),方便的文档目录等。
  6. 支持自定义代码生成模板。
  7. 支持集成发布到 RAP
  8. :new: 支持多模块、泛型。

Maven 和 Gradle

<dependency>
  <groupId>io.github.yedaxia</groupId>
  <artifactId>japidocs</artifactId>
  <version>1.2</version>
</dependency>
compile 'io.github.yedaxia:japidocs:1.2'

快速使用

  1. 我们以 spring 为例,一张图很容易就明白了 JApidocs 是怎么工作的了,你在设计接口的时候可以顺便就把相关的注释给填好了,这和 Java 程序员的编程习惯是保持一致的。

spring controller

这里你可能会对@ApiDoc注解感到迷惑,这也是唯一需要一点额外工作的地方,别急,下面马上就讲到它。

  1. @ApiDoc 是我们定义的一个注解,除非程序运行起来,否则我们是没办法知道 response 里面都包含有哪些内容。为了解决这个问题,我们折衷设计了这个基于RetentionPolicy.SOURCE的注解,它不会给现有的代码造成任何的负担。由于是基于 Java 源码进行解析的,所以你不需要依赖我们的 Jar 包,你可以在你自己的工程里面新建一个同名的类即可,当然你也可以直接添加我们的 Jar 包即可,里面已经为你准备好这个类了。

@Retention(RetentionPolicy.SOURCE)
@Target({ElementType.METHOD})
public @interface ApiDoc {

    /**
     * result class
     * @return
     */
	Class<?> value() default Null.class;

    /**
     * result class
     */
	Class<?> result() default Null.class;

    /**
     * request url
     */
	String url() default "";

    /**
     * request method
     */
	String method() default "get";

    final class Null{

    }
}

如果你用的是我们深度支持的 MVC 框架,那么你只需要写好返回的视图模型就可以了,这里不清楚的话可以看下 SpringDemo 下的例子写法,相信很容易就明白了。

  1. 集成依赖和运行程序

命令行模式:

下载all包,然后在和这个jar包相同目录下创建名称是docs.config的配置文件,里面可以配置这几个参数:

# windows用户注意用双斜杠'\\'或者反斜杠'/'

projectPath = 工程目录(必须)
docsPath = 文档输出目录(非必须,默认是${projectPath}/apidocs)
codeTplPath = 代码模版目录 (非必须,如果你需要自定义生成的代码才会用到。)
mvcFramework = [spring, play, jfinal, generic](非必须,代码内部有判断,如果出现误判的情况,可以通过这个强制指定)

配置好之后,在命令行窗口用 cd 把当前目录换成 jar 包所在的目录,运行该jar包就可以了。

java -jar ***-all.jar

代码模式

如果想做一些持续集成的话,代码模式还是比较方便的,直接添加依赖或者下载相关jar包,其中min包是不包含第三方依赖的。

compile 'io.github.yedaxia:japidocs:1.1.2'

只需要调用下面一句代码即可:

Docs.buildHtmlDocs(DocsConfig config);
  1. 自定义输出 Java 和 IOS 代码:

你可以把工程里面相关的代码模板文件拷贝出来,然后在配置参数声明好该路径即可,具体的模板文件如下: code template files

  1. 如何集成到 RAP 进行接口测试:

为了方便大家的集成,我自己搭建了一个 RAP 服务,去掉了验证码和支持中文 mock ,欢迎大家使用,当然如果你不嫌麻烦,也可以用官方的。

具体的集成请查看 Wiki

注意的地方

  1. 返回视图类不支持循环引用,会导致 stackoverflow。
class UserVO{
    BookVO book;
}

class BookKVO{
    UserVO user;
}
  1. JFinal 路由配置必须在 configRoute 方法体里,否则会解析失败。
    @Override
    public void configRoute(Routes me) {
        me.add("/api/v1/user", UserController.class);
        me.add("/api/v1/book", BookController.class);
        me.add(new AmdinRoutes());
    }
  1. JApiDocs 的使用必须配合视图模型类(JavaBean),JApiDocs 是通过静态解析源码来工作的,你返回给客户端的字段都必须在视图模型类中声明。

  2. 生成文档可以不需要依赖包,集成到 Rap 是需要依赖的,关于集成到 Rap 查看Wiki

支持和反馈

由于每个人写代码的习惯可能都不一样,虽然已经尽可能考虑到了多种不同的情况,但由于作者本人的认知和精力有限,难免会疏忽或者本身就存在有 bug 的情况,如果你在使用的过程中有碰到困难或者疑问,欢迎提issue或者加扣扣群进行反馈:70948803。

如果你觉得这个项目对你有用,不妨给个:star: star

你的支持是我前进的动力!

License

JApiDocs is available under the Apache 2 License. Please see the Licensing section for more information.

空文件

简介

一个 Java 程序员用的高效 API 文档生成工具。 展开 收起
Java
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
Java
1
https://gitee.com/cuiqunhao/JApiDocs.git
git@gitee.com:cuiqunhao/JApiDocs.git
cuiqunhao
JApiDocs
JApiDocs
master

搜索帮助

14c37bed 8189591 565d56ea 8189591