roctogen

Roctogen: a rust client library for the GitHub v3 API

This client API is generated from the upstream OpenAPI specification. The library currently supports webassembly and both tokio and non-tokio based asynchronous requests and minimal dependency blocking synchronous requests with a choice of different clients, enabled through cargo features:

• isahc feature (sync and non-tokio based async): Isahc HTTP client
• reqwest feature (async) Reqwest client
• ureq feature (sync) Ureq client

Install

Add the following to your Cargo.toml file

[dependencies]
roctogen = "0.12"

API

Documentation

API docs.

Endpoints.

Supported endpoints:

• Meta
• Issues
• Licenses
• Reactions
• Activity
• Projects
• Orgs
• Users
• Apps
• RateLimit
• Repos
• SecretScanning
• Packages
• Search
• Teams
• Markdown
• OauthAuthorizations
• Actions
• Migrations
• Gists
• CodesOfConduct
• Pulls
• Gitignore
• EnterpriseAdmin
• Git
• Scim
• CodeScanning
• Checks
• Billing
• Interactions
• Codespaces
• Emojis

Usage

A quick example of this library:

use roctogen::api::{self, repos};
use roctogen::auth::Auth;

let auth = Auth::None;
let per_page = api::PerPage::new(10);

let mut params: repos::ReposListCommitsParams = per_page.as_ref().into();
params = params.author("fussybeaver").page(2);

repos::new(&auth).list_commits("fussybeaver", "bollard", Some(params));

Async

All the async methods are suffixed with _async, and are available on the wasm target or isahc and reqwest adapters.

Webassembly

To compile for webassembly, you can use wasm-pack or compile with the wasm32-unknown-unknown target:

$ wasm-pack build

$ cargo build --target wasm32-unknown-unknown

If you are building a cloudflare worker, you would use the wrangler wrapper:

$ wrangler preview --watch

Client adapters

Building on non-wasm targets generally requires adopting a feature for the desired client adapter.

Isahc

Compiling for the isahc client required the isahc feature:

$ cargo build --features isahc

Reqwest

Compiling for the reqwest client required the reqwest feature:

$ cargo build --features reqwest

Ureq

Compiling for the ureq client required the ureq feature:

$ cargo build --features ureq

GitHub preview features

GitHub supports a phased rollout of non-stable endpoints behind header flags. These are supported in this library through cargo feature flags.

$ cargo build --features squirrel-girl

Generate the API

The majority of code is generated through the Swagger OpenAPI generator (version 3). Building requires the mvn Java build tool, pegged at Java version 8 (so you'll need an appropriate JDK).

$ mvn -D org.slf4j.simpleLogger.defaultLogLevel=info clean compiler:compile generate-resources

Tests

Beware, tests that are not run with the mock feature are currently still doing real HTTP requests to the GitHub API.

Run the wasm tests:

$ wasm-pack test --firefox --headless

Run the sync tests:

$ cargo test --features isahc,mercy,squirrel-girl,inertia,starfox --target x86_64-unknown-linux-gnu -- --nocapture

In order to avoid GitHub's API rate limiting, you can run the non-wasm tests using wiremock. You'll need to start wiremock in the background:

$ docker run -d --name wiremock -p 8080:8080 -v $PWD/tests/stubs:/home/wiremock
rodolpheche/wiremock

Regenerate the wiremock stubs

You should regenerate the stubs if the remote API has changed:

$ docker run -d --name wiremock -p 8080:8080 -v $PWD/tests/stubs:/home/wiremock -u (id -u):(id -g) rodolpheche/wiremock --verbose --proxy-all="https://api.github.com" --record-mappings

License: Apache-2.0