Crate roctogen[][src]

Expand description

license docs GitHub workflow

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:


Add the following to your Cargo.toml file

roctogen = "0.6"



API docs.


Supported endpoints:


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 ="fussybeaver").page(2);

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


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


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.


Compiling for the isahc client required the isahc feature:

$ cargo build --features isahc


Compiling for the reqwest client required the reqwest feature:

$ cargo build --features reqwest


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


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

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="" --record-mappings


pub use endpoints as api;



Endpoints module and PerPage struct/impl