repository·main·Indexed 20 days ago
https://github.com/tamasfe/aideA code-first API documentation library for Rust designed to automate the generation of OpenAPI 3.1.x specifications from source code. It leverages schemars for schema generation and provides traits like OperationInput and OperationOutput to document HTTP parameters and responses. Aide includes integration for Axum and provides tools for customizing documentation via the WithApi wrapper and ApiOverride trait.
Aide has a growing ecosystem of community-maintained projects, including:
axum_typed_multipart that enables documentation generation for multipart requests.To run the minimal to-do application built with axum and documented using aide, use the following cargo command. Once running, the documentation is served locally at http://localhost:3000.
cargo run --bin example-axumTo run the minimal to-do Axum Cloudflare Worker example, use the following command. Once running, the documentation is served locally at http://localhost:3000.
npm run devAide uses a thread-local GenContext to manage settings for API documentation generation. Most configuration is performed using top-level functions that modify this context for the current thread. This allows you to set global behaviors (like error handling or schema extraction) without passing a context object through every function call in your application.
// Example of configuring the context
// These settings apply to the current thread
aide::extract_schemas(true);
aide::inferred_empty_response_status(204);
aide::strip_query_null_types(true);aide is a code-first OpenAPI 3.1.x documentation generator. It uses a combination of type-based generation and declarative transformations to minimize manual documentation effort.
aide leverages the schemars crate for schema generation. For JSON-based APIs, you simply need to implement schemars::JsonSchema alongside serde's Serialize and Deserialize traits on your types.
aide uses the OperationInput and OperationOutput traits to automatically document HTTP parameters and responses. For example, if you use an axum::Json<T> extractor, aide will automatically generate an application/json request body documentation using the schema of T, provided T implements JsonSchema.
Manual documentation is handled through composable transform functions and a builder-pattern API, allowing you to augment the automatically generated schema with specific details.
Aide allows you to customize how types are documented in your OpenAPI specification using the WithApi<T> wrapper. This is useful for two scenarios:
OperationInput or OperationOutput, you can use WithApi with a custom ApiOverride implementation to provide different documentation metadata.OperationInput or OperationOutput to make them compatible with Aide's documentation generation.Use this when you want to override the documentation for a specific concrete type.
use aide::{ApiOverride, OperationInput, WithApi};
#[derive(Eq, PartialEq, Debug)]
struct SomeType;
#[derive(Debug)]
struct MyApiOverride;
impl ApiOverride for MyApiOverride {
type Target = SomeType;
}
// Implement OperationInput (or OperationOutput) on the override type to define custom docs
impl OperationInput for MyApiOverride {
// override stuff here
}
// Use WithApi in your handler
async fn my_handler(WithApi(ty, ..): WithApi<MyApiOverride>) -> bool {
assert_eq!(ty, SomeType);
true
}Use this when you want to apply documentation logic to a generic wrapper (e.g., a custom XML or JSON wrapper) across multiple target types.
use std::marker::PhantomData;
use aide::{ApiOverride, OperationInput, WithApi};
#[derive(Eq, PartialEq, Debug)]
struct SomeType;
#[derive(Eq, PartialEq, Debug)]
struct CustomXML<T>(T);
#[derive(Debug)]
struct MyCustomXML<T>(PhantomData<T>);
impl<T> ApiOverride for MyCustomXML<T> {
type Target = CustomXML<T>;
}
impl<T> OperationInput for MyCustomXML<T> {
// override stuff with access to T
}
async fn my_handler(WithApi(ty, ..): WithApi<MyCustomXML<SomeType>>) -> bool {
assert_eq!(ty, CustomXML(SomeType));
true
}use aide::{ApiOverride, OperationInput, WithApi};
#[derive(Eq, PartialEq, Debug)]
struct SomeType;
#[derive(Debug)]
struct MyApiOverride;
impl ApiOverride for MyApiOverride {
type Target = SomeType;
}
impl OperationInput for MyApiOverride {
// override stuff
}
async fn my_handler(WithApi(ty, ..): WithApi<MyApiOverride>) -> bool {
assert_eq!(ty, SomeType);
true
}During the OpenAPI generation process, some errors may occur. By default, aide takes no action on these errors (they are swallowed), which might indicate bugs in the documentation logic.
To handle these errors, you can register an error handler in the thread-local context using aide::generate::on_error.
Warning: It is not advised to simply panic on all errors, especially in production environments, as aide may produce false positives when contextual information is insufficient.
aide has no features enabled by default. You must enable specific features depending on your requirements.
macros: Enables additional helper macros, including the OperationIo derive macro.If using axum, you can enable specific feature gates for various extractors and types:
axum (base integration)axum-formaxum-jsonaxum-matched-pathaxum-multipartaxum-original-uriaxum-queryaxum-tokio (for ConnectInfo)axum-ws (WebSockets)axum-extraaxum-extra-cookieaxum-extra-cookie-privateaxum-extra-formaxum-extra-headersaxum-extra-queryaxum-extra-json-deserializerswaggerredocscalarThe OperationIo derive macro (provided by aide_macros) simplifies implementing OperationInput and OperationOutput. You can use attributes to customize which parts of the trait are implemented:
#[aide(input)]: Implements OperationInput.#[aide(output)]: Implements OperationOutput.#[aide(input, output)]: Implements both.#[aide(input_with = "Type", output_with = "Type")]: Uses specific types for the input/output logic.#[aide(json_schema)]: Adds JsonSchema bounds to the implementation.#[derive(OperationIo)]
#[aide(input, output)]
struct MyDataWrapper(String);When enabled, null types are automatically removed from query parameter schemas during finalization. This is useful because query strings cannot express null values (a parameter is either present or absent). This is enabled by default.
// Disable automatic stripping of null types
aide::strip_query_null_types(false);Controls whether all theoretically possible error responses (including framework-specific ones) are output. This is disabled by default.
// Enable outputting all possible error responses
aide::all_error_responses(true);