1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

//! # Aide
//!
//! `aide` is a code-first [Open API](https://www.openapis.org/) 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](https://github.com/tamasfe/aide/tree/master/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`](https://docs.rs/linkme/latest/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 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.
//!
//! ## Type-based Generation
//!
//! The library uses [`schemars`] for schema generation for types.
//! It should be enough to slap [`JsonSchema`](schemars::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`](schemars::JsonSchema).
//!
//! ## Declarative Documentation
//!
//! All manual documentation is based on composable [`transform`]
//! functions and builder-pattern-like API.
//!
//! ## Supported Frameworks
//!
//! - [axum](https://docs.rs/axum/latest/axum/): [`aide::axum`](axum).
//! - [actix-web](https://docs.rs/actix-web/latest/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::gen::on_error`](crate::gen::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`
//! - `serde_qs` (when used with `axum`)
//!
//! ### axum integration
//!
//! `axum` and its features gates:
//!
//! - `axum`
//! - `axum-ws`
//! - `axum-multipart`
//! - `axum-headers`
//!
//! `axum-extra` and its features gates:
//!
//! - `axum-extra`
//! - `axum-extra-cookie`
//! - `axum-extra-cookie-private`
//! - `axum-extra-form`
//! - `axum-extra-query`
//!
//! ## MSRV
//!
//! The library will always support the latest stable Rust version,
//! it might support older versions but without guarantees.
//!
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![warn(clippy::pedantic, missing_docs)]
#![allow(
    clippy::default_trait_access,
    clippy::module_name_repetitions,
    clippy::wildcard_imports,
    clippy::too_many_lines,
    clippy::single_match_else,
    clippy::manual_let_else
)]

#[macro_use]
mod macros;
mod impls;

pub mod error;
pub mod gen;
pub mod operation;

pub mod openapi;
pub mod transform;
pub mod util;

#[cfg(feature = "axum")]
pub mod axum;

mod helpers;
#[cfg(feature = "redoc")]
pub mod redoc;

#[cfg(feature = "scalar")]
pub mod scalar;

pub use helpers::{no_api::NoApi, with_api::ApiOverride, with_api::WithApi, use_api::UseApi};

pub use error::Error;
pub use operation::{OperationInput, OperationOutput};

#[cfg(feature = "macros")]
pub use aide_macros::OperationIo;