32 releases (7 breaking)
Uses new Rust 2021
|new 0.8.0-rc.1||Nov 21, 2022|
|0.6.4||Nov 11, 2022|
|0.4.3||Mar 3, 2022|
|0.3.6||Dec 12, 2021|
|0.1.5||Oct 16, 2020|
#419 in Development tools
1,622 downloads per month
Used in 2 crates
A code-first API documentation and utility library.
aide is a code-first Open API documentation
generator library. It aims for tight integrations with frameworks and
following their conventions, while tries to be out
of the way when it is not needed.
The goal is to minimize the learning curve, mental context switches and make documentation somewhat slightly less of a chore.
See the examples to see how Aide is used with various frameworks.
Currently only Open API version
3.1.0 is supported.
Previous releases of aide relied heavily on macros, and the
linkme crate for automagic global state.
While it all worked, macros were hard to reason about,
rustfmt did not work with them, code completion was hit-and-miss.
0.5.0, aide was rewritten and instead it is based on on good old functions,
type inference and declarative APIs based on the builder pattern.
Now all documentation can be traced in the source code[^1], no more macro and global magic all over the place.[^2]
[^1]: and with [tracing] spans
[^2]: A thread-local context is still used for some settings and shared state.
The library uses [
schemars] for schema generation for types.
It should be enough to slap
Serialize/Deserialize for JSON-based APIs.
Additionally the [
OperationInput] and [
are used for extractor and response types in frameworks to automatically generate
expected HTTP parameter and response documentation.
For example a
Json<T> extractor will generate an
request body with the schema of
T if it implements
All manual documentation is based on composable [
functions and builder-pattern-like API.
- actix-web is not
0.5.0only due to lack of developer capacity, but it's likely to be supported again in the future. If you use
actix-webyou can still use the macro-based
0.4.*version of the library for the time being.
Some errors occur during code generation, these are usually safe to ignore but might indicate bugs.
By default no action is taken on errors, in order to handle them
it is possible to register an error handler in the thread-local context
False positives are chosen over silently swallowing potential errors, these might happen when there is not enough contextual information to determine whether an error is in fact an error. It is important to keep this in mind, without any filters simply panicking on all errors is not advised, especially not in production.
No features are enabled by default.
macros: additional helper macros
Third-party trait implementations
axum and its features gates:
axum-extra and its features gates:
The library will always support the latest stable Rust version, it might support older versions but without guarantees.