public-api

通过分析来自 rustdoc +nightly 的rustdoc JSON输出文件来列出并比较Rust库crate的公共API。

用法

… 作为Rust库

查看docs.rs以获取库文档和示例代码。

… 作为CLI

使用cargo public-api进行CLI用例。

… 作为CI检查

在CI中运行常规的 cargo test 命令，您将能够

• 防止意外更改公共API
• 审查故意更改的公共API差异

首先将推荐的库的最新版本添加到您的 [dev-dependencies]

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

然后向您的项目添加以下测试。作为以下测试代码的作者，我特此将其与CC0关联，并在法律允许的范围内放弃所有版权和相关或邻近的权利

#[test]
fn public_api() {
    // Install a compatible nightly toolchain if it is missing
    rustup_toolchain::install(public_api::MINIMUM_NIGHTLY_RUST_VERSION).unwrap();

    // Build rustdoc JSON
    let rustdoc_json = rustdoc_json::Builder::default()
        .toolchain(public_api::MINIMUM_NIGHTLY_RUST_VERSION)
        .build()
        .unwrap();

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

    // Assert that the public API looks correct
    expect_test::expect_file!["public-api.txt"].assert_eq(&public_api.to_string());
}

在您首次运行测试之前，您需要祝福当前的公共API

UPDATE_EXPECT=1 cargo test public_api

这将在您的项目中创建一个 tests/public-api.txt 文件，您需要使用 git add 与您的其他项目文件一起添加。每次更改公共API时，您都需要使用上述命令再次祝福它。如果您忘记祝福，测试将失败，并附带有关如何祝福的说明。

变更日志

请参阅 CHANGELOG.md。

维护者

请参阅此处。