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(String::from("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(String::from("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(String::from("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
cargo public-api
contains
additional helpers for that.Structs
PublicApi::from_rustdoc_json_str
.Enums
Constants
Type Definitions
std::result::Result<T, public_api::Error>
.