jcabi-github - Java实现的面向对象GitHub API适配器

代码行数

这是一个GitHub RESTful API的Java适配器。市场上有一些类似的实现，但jcabi-github非常注重面向对象的编程原则。此外，我们还独特地实现了GitHub服务器端功能，你可以在单元测试中使用它，无需在单元/集成测试期间连接到GitHub。请阅读这个库的创建者Yegor Bugayenko的博客文章 面向对象的Github API。

需要Java 8或更高版本。

更多详情请见：github.jcabi.com。

你也可以在这个Telegram聊天组获得帮助。

com.jcabi.github 包中的类集是面向对象的API。使用方法如下：

使用Github的API

默认情况下，该库与Github的API (https://api.github.com) 配合使用

import com.jcabi.github.*;
public class Main {
  public static void main(String[] args) throws IOException {
    Github github = new RtGithub(".. 你的OAuth令牌 ..");
    Repo repo = github.repos().get(
        new Coordinates.Simple("octocat/Hello-World")
    );
    Issue issue = repo.issues().create("测试标题", "测试描述");
    issue.comments().post("我的第一条评论！");
  }
}

使用Github Enterprise或其他

如果你想通过其他域名使用Github的API，你可以使用 RtGithub 类的URI构造函数。例如，如果你在域名 https://github.mydomain.com 下部署了自己的Github实例，可以这样做：

final Github github = new RtGithub(URI.create("https://github.mydomain.com"));

//或者

final Github github = new RtGithub(
    "<<oauth2_token>>",
    URI.create("https://github.mydomain.com")
);

//或者

final Github github = new RtGithub(
    "username", "password",
    URI.create("https://github.mydomain.com")
);

不要更改或掩盖你的URI！在不同的域名下使用Github是可以的，但不要更改URI的路径。更改请求路径是不可能的，因为这个库的整个架构都依赖于Github的URI路径。

对于更复杂的配置，你可以使用自定义的 Request 来实例化 RtGithub，方法是使用 RtGithub(Request) 构造函数。请确保正确配置 Request。参考默认Request的创建方式 -- 你基本上需要做同样的事情。

API的模拟实现

我们还提供了 MkGithub，这是GitHub服务器的一个模拟版本，你可以在单元测试中使用它，例如：

import com.jcabi.github.*;
public class FooTest {
  public void submitsCommentToGithubIssue() {
    final Repo repo = new MkGithub().repos().create(
      Json.createObjectBuilder().add("name", "test").build()
    );
    final Issue issue = repo.issues().create("how are you?", "");
    new Foo(issue).doSomething(); // 应该向问题发送一条消息
    MasterAssert.assertThat(
      issue.comments().iterate(),
      Matchers.iterableWithSize(1)
    );
  }
}

如何贡献？

fork仓库，进行修改，提交pull request。我们承诺会在当天审查你的修改，如果看起来没问题就会应用到 master 分支。

在提交pull request之前，请运行Maven（3.1或更高版本！）构建：

$ mvn clean install -Pqulice

有许多集成测试会检查我们的类与实际的Github账户的交互。为了运行这些测试，你需要创建新的Github OAuth访问令牌（如何创建？），并在命令行中提供它们，如下所示：

$ mvn clean install -Dit.test=RtGistITCase -Dfailsafe.github.key=<token> -Dfailsafe.github.key.second=<second-token> -Dfailsafe.github.repo=<repo>

将 <token> 和 <second-token> 替换为两个不同Github账户的OAuth访问令牌。这个测试用例将尝试将第一个账户的gist复刻到第二个账户。将 <repo> 替换为你在第一个账户中创建的仓库名称（仅用于测试目的），例如 yegor256/test。OAuth访问令牌应该在各自的仓库中拥有集成测试套件所需的所有范围的权限（包括默认情况下未设置的 delete_repo！）。

请注意，不同的集成测试可能需要具有不同范围权限的密钥。要运行所有集成测试，密钥应该具有以下OAuth范围：

read:org
repo
delete_repo
admin:public_key
gist
admin:repo_hook
user
user:email

RtForksITCase 需要额外的参数 -Dfailsafe.github.organization=<organization>，其中 <organization> 是用于复刻测试Github仓库的组织名称。

如果只想运行静态分析检查，请使用以下命令：

$ mvn clean install -DskipTests -Dinvoker.skip=true -Pqulice