Crate roctogen[−][src]

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 synchronous requests with the Isahc HTTP client.

Install

Add the following to your Cargo.toml file

[dependencies]
roctogen = "0.2"

API

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 (currently only supported on the wasm target).

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

Building on non-wasm targets generally requires adopting a feature for the desired client adapter. This library only supports isahc at the moment, but other adapters are planned, and contributions are welcome.

Compiling for the isahc client required the isahc feature:

$ cargo build --features isahc

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

Re-exports

pub use endpoints as api;

Modules

adapters
auth
endpoints	Endpoints module and `PerPage` struct/impl
models