#semver #rustdoc-json #diff #cargo


List and diff the public API of Rust library crates. Relies on rustdoc JSON output from the nightly toolchain.

50 releases (25 breaking)

new 0.33.1 Nov 29, 2023
0.32.0 Aug 25, 2023
0.31.2 Jun 18, 2023
0.28.0 Mar 25, 2023
0.12.4 Jul 24, 2022

#28 in Development tools

Download history 7374/week @ 2023-08-10 5522/week @ 2023-08-17 1923/week @ 2023-08-24 1505/week @ 2023-08-31 1622/week @ 2023-09-07 1499/week @ 2023-09-14 1415/week @ 2023-09-21 1449/week @ 2023-09-28 1720/week @ 2023-10-05 1647/week @ 2023-10-12 1820/week @ 2023-10-19 1536/week @ 2023-10-26 1680/week @ 2023-11-02 1933/week @ 2023-11-09 2226/week @ 2023-11-16 1653/week @ 2023-11-23

7,720 downloads per month
Used in 12 crates (6 directly)

MIT license



List and diff the public API of Rust library crates by analyzing rustdoc JSON output files from rustdoc +nightly.


… as a Rust library

See docs.rs for library documentation and example code.

… as a CLI

Use cargo public-api for CLI use cases.

… as a CI Check

With a regular cargo test that you run in CI you will be able to

  • prevent accidental changes to your public API
  • review the public API diff of deliberate changes

First add the latest versions of the necessary libraries to your [dev-dependencies]:

cargo add --dev \
    rustup-toolchain \
    rustdoc-json \
    public-api \

Then add the following test to your project. As the author of the below test code, I hereby associate it with CC0 and to the extent possible under law waive all copyright and related or neighboring rights to it:

fn public_api() {
    // Install a compatible nightly toolchain if it is missing

    // Build rustdoc JSON
    let rustdoc_json = rustdoc_json::Builder::default()

    // Derive the public API from the rustdoc JSON
    let public_api = public_api::Builder::from_rustdoc_json(rustdoc_json)

    // Assert that the public API looks correct

Before you run the test the first time you need to bless the current public API:

UPDATE_EXPECT=1 cargo test public_api

This creates a tests/public-api.txt file in your project that you git add together with your other project files. Whenever you change the public API, you need to bless it again with the above command. If you forget to bless, the test will fail, together with instructions on how to bless.




See here.


~35K SLoC