Crate public_api
source ·Expand description
This library gives you the public API of a library crate, in the form of a list of public items in the crate. Public items are items that other crates can use. Diffing is also supported.
If you want a convenient CLI for this library, you should use cargo public-api.
As input to the library, a special output format from cargo doc
is used,
which goes by the name rustdoc JSON. Currently, only cargo doc
from
the Nightly toolchain can produce rustdoc JSON for a library. You build
rustdoc JSON like this:
cargo +nightly rustdoc --lib -- -Z unstable-options --output-format json
Consider using rustdoc_json
instead of invoking the above command yourself.
The main entry point to the library is PublicApi::from_rustdoc_json_str
,
so please read its documentation.
Examples
The two main use cases are listing the public API and diffing different versions of the same public APIs.
List all public items of a crate (the public API)
use std::error::Error;
use public_api::{Options, PublicApi};
fn main() -> Result<(), Box<dyn Error>> {
let json_path = rustdoc_json::Builder::default()
.toolchain("nightly")
.manifest_path("test-apis/example_api-v0.2.0/Cargo.toml")
.build()?;
let public_api = PublicApi::from_rustdoc_json(json_path, Options::default())?;
for public_item in public_api.items() {
println!("{public_item}");
}
Ok(())
}
Diff two versions of a public API
use std::error::Error;
use public_api::{diff::PublicApiDiff, Options, PublicApi};
fn main() -> Result<(), Box<dyn Error>> {
let options = Options::default();
let old_json = rustdoc_json::Builder::default()
.toolchain("nightly")
.manifest_path("test-apis/example_api-v0.1.0/Cargo.toml")
.build()?;
let old = PublicApi::from_rustdoc_json(old_json, options)?;
let new_json = rustdoc_json::Builder::default()
.toolchain("nightly")
.manifest_path("test-apis/example_api-v0.2.0/Cargo.toml")
.build()?;
let new = PublicApi::from_rustdoc_json(new_json, options)?;
let diff = PublicApiDiff::between(old, new);
println!("{diff:#?}");
Ok(())
}
The most comprehensive example code on how to use the library can be found in the thin binary wrapper around the library, see https://github.com/Enselic/cargo-public-api/blob/main/public-api/src/main.rs.
Modules
- Contains facilities that allows you diff public APIs between releases and commits.
cargo public-api
contains additional helpers for that. - The module tp contain all token handling logic.
Structs
- Contains various options that you can pass to
PublicApi::from_rustdoc_json
. - The public API of a crate
Enums
- Enumerates all errors that can currently occur within this crate.
Constants
- This constant defines the minimum version of nightly that is required in order for the rustdoc JSON output to be parsable by this library. Note that this library is implemented with stable Rust. But the rustdoc JSON that this library parses can currently only be produced by nightly.
- MINIMUM_RUSTDOC_JSON_VERSIONDeprecatedDeprecated, use
MINIMUM_NIGHTLY_VERSION
instead.
Type Definitions
- Shorthand for
std::result::Result<T, public_api::Error>
.