#github

roctogen

Github API and models generated from the official swagger OpenAPI specification

15 releases (breaking)

0.12.0 Jan 6, 2022
0.11.0 Oct 24, 2021
0.10.0 Aug 15, 2021
0.8.0 Jul 12, 2021
0.1.2 Mar 22, 2021

#862 in Web programming

Download history 5/week @ 2023-01-25 6/week @ 2023-02-01 46/week @ 2023-02-08 45/week @ 2023-02-15 2/week @ 2023-02-22 1/week @ 2023-03-08 2/week @ 2023-03-15 30/week @ 2023-03-22 38/week @ 2023-04-12 4/week @ 2023-04-19 15/week @ 2023-05-03 18/week @ 2023-05-10

53 downloads per month

Apache-2.0

4.5MB
72K SLoC

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:

Install

Add the following to your Cargo.toml file

[dependencies]
roctogen = "0.12"

API

Documentation

API docs.

Endpoints.

Supported endpoints:

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

Dependencies

~2–14MB
~256K SLoC