Crate aide

Crate aide 

Source
Expand description

§Aide

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.

With 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 code1, no more macro and global magic all over the place.2

§Type-based Generation

The library uses schemars for schema generation for types. It should be enough to slap JsonSchema alongside serde’s Serialize/Deserialize for JSON-based APIs.

Additionally the OperationInput and OperationOutput traits 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 application/json request body with the schema of T if it implements JsonSchema.

§Declarative Documentation

All manual documentation is based on composable transform functions and builder-pattern-like API.

§Supported Frameworks

  • axum: aide::axum.
  • actix-web is not supported since 0.5.0 only due to lack of developer capacity, but it’s likely to be supported again in the future. If you use actix-web you can still use the macro-based 0.4.* version of the library for the time being.

§Errors

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 with aide::generate::on_error.

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.

§Feature Flags

No features are enabled by default.

  • macros: additional helper macros

§Third-party trait implementations

  • bytes
  • http

§axum integration

axum and its features gates:

  • axum
  • axum-form
  • axum-json
  • axum-matched-path
  • axum-multipart
  • axum-original-uri
  • axum-query
  • axum-tokio (for ConnectInfo)
  • axum-ws (WebSockets)

axum-extra and its features gates:

  • axum-extra
  • axum-extra-cookie
  • axum-extra-cookie-private
  • axum-extra-form
  • axum-extra-headers
  • axum-extra-query
  • axum-extra-json-deserializer

§MSRV

The library will always support the latest stable Rust version, it might support older versions but without guarantees.

  1. and with tracing spans ↩

  2. A thread-local context is still used for some settings and shared state. ↩

Re-exports§

pub use error::Error;
pub use operation::OperationInput;
pub use operation::OperationOutput;

Modules§

axumaxum
Open API code generation for axum.
error
Crate-wide error types.
generate
Thread-local context for common settings for documentation generation.
openapi
Type definitions taken from https://github.com/glademiller/openapiv3/pull/58
operation
Traits and utilities for schema generation for operations (handlers).
redocredoc
Generate Redoc ui. This feature requires the axum feature.
scalarscalar
Generate Scalar API References. This feature requires the axum feature.
swaggerswagger
Generate Swagger ui. This feature requires the axum feature.
transform
Transformers wrap a part of or the entirety of OpenApi and enable modifications with method chaining in a declarative way.
util
Miscellaneous utilities.

Structs§

NoApi
Allows non OperationInput or OperationOutput types to be used in aide handlers with a default empty documentation.
UseApi
Allows non OperationInput or OperationOutput types to be used in aide handlers with the api documentation of [A].
WithApi
Allows non OperationInput or OperationOutput types to be used in aide handlers with a provided documentation.

Traits§

ApiOverride
Trait that allows implementing a custom Api definition for any type.
IntoApi
helper trait to allow simplified use of UseApi in responses

Derive Macros§

OperationIomacros
A helper to reduce boilerplate for implementing OperationInput and OperationOutput for common use-cases.