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, fs::read_to_string};
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_str(&read_to_string(&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, fs::read_to_string};
use public_api::{diff::PublicItemsDiff, 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_str(&read_to_string(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_str(&read_to_string(new_json)?, options)?;
let diff = PublicItemsDiff::between(old.items, new.items);
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
Functions
Type Definitions
std::result::Result<T, public_api::Error>
.