[](https://opensource.org/licenses/Apache-2.0)
[](https://docs.rs/roctogen/)
[](https://github.com/fussybeaver/roctogen/actions/workflows/default.yml)
## Roctogen: a rust client library for the GitHub v3 API
This client API is generated from the [upstream OpenAPI
specification](https://github.com/github/rest-api-description/). The library currently supports
webassembly and synchronous requests with the [Isahc HTTP client](https://github.com/sagebind/isahc).
## Install
Add the following to your `Cargo.toml` file
```nocompile
[dependencies]
roctogen = "0.2"
```
## API
### Documentation
[API docs](https://docs.rs/roctogen/latest).
[Endpoints](https://docs.rs/roctogen/latest/roctogen/endpoints/index.html).
Supported endpoints:
---
- [Meta](https://docs.rs/roctogen/latest/roctogen/endpoints/meta/struct.Meta.html)
- [Issues](https://docs.rs/roctogen/latest/roctogen/endpoints/issues/struct.Issues.html)
- [Licenses](https://docs.rs/roctogen/latest/roctogen/endpoints/licenses/struct.Licenses.html)
- [Reactions](https://docs.rs/roctogen/latest/roctogen/endpoints/reactions/struct.Reactions.html)
- [Activity](https://docs.rs/roctogen/latest/roctogen/endpoints/activity/struct.Activity.html)
- [Projects](https://docs.rs/roctogen/latest/roctogen/endpoints/projects/struct.Projects.html)
- [Orgs](https://docs.rs/roctogen/latest/roctogen/endpoints/orgs/struct.Orgs.html)
- [Users](https://docs.rs/roctogen/latest/roctogen/endpoints/users/struct.Users.html)
- [Apps](https://docs.rs/roctogen/latest/roctogen/endpoints/apps/struct.Apps.html)
- [AuditLog](https://docs.rs/roctogen/latest/roctogen/endpoints/audit_log/struct.AuditLog.html)
- [RateLimit](https://docs.rs/roctogen/latest/roctogen/endpoints/rate_limit/struct.RateLimit.html)
- [Repos](https://docs.rs/roctogen/latest/roctogen/endpoints/repos/struct.Repos.html)
- [SecretScanning](https://docs.rs/roctogen/latest/roctogen/endpoints/secret_scanning/struct.SecretScanning.html)
- [Packages](https://docs.rs/roctogen/latest/roctogen/endpoints/packages/struct.Packages.html)
- [Search](https://docs.rs/roctogen/latest/roctogen/endpoints/search/struct.Search.html)
- [Teams](https://docs.rs/roctogen/latest/roctogen/endpoints/teams/struct.Teams.html)
- [Markdown](https://docs.rs/roctogen/latest/roctogen/endpoints/markdown/struct.Markdown.html)
- [OauthAuthorizations](https://docs.rs/roctogen/latest/roctogen/endpoints/oauth_authorizations/struct.OauthAuthorizations.html)
- [Actions](https://docs.rs/roctogen/latest/roctogen/endpoints/actions/struct.Actions.html)
- [Migrations](https://docs.rs/roctogen/latest/roctogen/endpoints/migrations/struct.Migrations.html)
- [Gists](https://docs.rs/roctogen/latest/roctogen/endpoints/gists/struct.Gists.html)
- [CodesOfConduct](https://docs.rs/roctogen/latest/roctogen/endpoints/codes_of_conduct/struct.CodesOfConduct.html)
- [Pulls](https://docs.rs/roctogen/latest/roctogen/endpoints/pulls/struct.Pulls.html)
- [Gitignore](https://docs.rs/roctogen/latest/roctogen/endpoints/gitignore/struct.Gitignore.html)
- [EnterpriseAdmin](https://docs.rs/roctogen/latest/roctogen/endpoints/enterprise_admin/struct.EnterpriseAdmin.html)
- [Git](https://docs.rs/roctogen/latest/roctogen/endpoints/git/struct.Git.html)
- [Scim](https://docs.rs/roctogen/latest/roctogen/endpoints/scim/struct.Scim.html)
- [CodeScanning](https://docs.rs/roctogen/latest/roctogen/endpoints/code_scanning/struct.CodeScanning.html)
- [Checks](https://docs.rs/roctogen/latest/roctogen/endpoints/checks/struct.Checks.html)
- [Billing](https://docs.rs/roctogen/latest/roctogen/endpoints/billing/struct.Billing.html)
- [Interactions](https://docs.rs/roctogen/latest/roctogen/endpoints/interactions/struct.Interactions.html)
- [Emojis](https://docs.rs/roctogen/latest/roctogen/endpoints/emojis/struct.Emojis.html)
## Usage
A quick example of this library:
```rust
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`](https://github.com/rustwasm/wasm-pack) or compile with the
`wasm32-unknown-unknown` target:
```nocompile
$ wasm-pack build
```
```nocompile
$ cargo build --target wasm32-unknown-unknown
```
If you are building a [cloudflare worker](https://workers.cloudflare.com/), you would use the
`wrangler` wrapper:
```nocompile
$ wrangler preview --watch
```
### Isahc
Building on non-`wasm` targets generally requires adopting a feature for the desired
client adapter. This library only supports [`isahc`](https://github.com/sagebind/isahc) at the
moment, but other adapters are planned, and contributions are welcome.
Compiling for the [`isahc`](https://github.com/sagebind/isahc) client required the `isahc` feature:
```nocompile
$ 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.
```nocompile
$ cargo build --features squirrel-girl
```
## Generate the API
The majority of code is generated through the [Swagger OpenAPI
generator](https://github.com/swagger-api/swagger-codegen) (version 3). Building requires the
[`mvn`](https://maven.apache.org/install.html) Java build tool, pegged at Java version 8 (so
you'll need an appropriate JDK).
```nocompile
$ 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:
```nocompile
$ wasm-pack test --firefox --headless
```
Run the sync tests:
```nocompile
$ 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:
```nocompile
$ 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:
```nocompile
$ 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