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
150
151
152
153
154
155
156
157
158
159
160
//! Optional OpenAPI 3.1 support for Axum services.
//!
//! Enable the `openapi` feature to use the re-exported [`utoipa`] crate and
//! [`OpenApiDocs`] for ReDoc or RapiDoc documentation pages.
//! Prefer the [`utoipa`] and [`redoc`] re-exports to use matching dependency types.
//! Annotate handlers with [`utoipa::path`] and register them using
//! [`OpenApiRouter`] and [`route!`]. Applications describe business
//! DTOs, security schemes, and responses; footing supplies schemas for its
//! public HTTP payloads and checks endpoint-contract coverage.
//! Modules can each return an [`OpenApiRouter`] and combine them with
//! [`OpenApiRouter::merge`], preserving route/document/contract consistency and
//! checking conflicts before the combined router is served. Use complete paths;
//! merging does not add a prefix or change application state types.
//!
//! Documentation pages require an explicit [`DocsUi`] when constructing
//! [`OpenApiDocs`]. Features control which assets are available; they do not
//! select a default renderer or mount any routes. Enable `rapidoc-embedded` or
//! `redoc-embedded` to use the corresponding bundled UI; either feature also
//! enables `openapi`. Both can be enabled in the same application, with each
//! page choosing its own UI. See [`DocsUi`] for the feature/constructor mapping
//! and embedded examples. Caller-supplied bytes or URLs through [`DocsAssets`]
//! require only `openapi`, for either renderer.
//!
//! [`crate::http::ProblemDetails`], [`crate::pagination::CursorPage`],
//! [`crate::pagination::OffsetPage`], field violations, health payloads, and
//! request identifiers implement [`utoipa::ToSchema`]. [`crate::http::ApiProblem`]
//! implements [`utoipa::ToResponse`] with `application/problem+json` content.
//! Use `response = inline(ApiProblem)` for an inline response, or register it in
//! `components(responses(ApiProblem))` to share a response component.
//! Pagination extractors and query types implement [`utoipa::IntoParams`] using
//! default limits. Configure custom limits with
//! [`OpenApiRoute::with_cursor_pagination`] or [`OpenApiRoute::with_offset_pagination`]
//! to install the runtime extension and update the document together. The
//! parameter helper functions remain available for manually assembled documents.
//!
//! ```rust
//! use axum::{Json, Router};
//! use footing::{http::{ApiProblem, CursorPagination, openapi::{OpenApiRouter, route, utoipa}},
//! pagination::{CursorPage, PageLimits}};
//! use utoipa::OpenApi;
//!
//! #[derive(serde::Serialize, utoipa::ToSchema)]
//! struct Item { id: u64 }
//!
//! #[utoipa::path(get, path = "/items", params(CursorPagination), responses(
//! (status = 200, body = CursorPage<Item>),
//! (status = 400, response = inline(ApiProblem))
//! ))]
//! async fn items(page: CursorPagination) -> Result<Json<CursorPage<Item>>, ApiProblem> {
//! CursorPage::new(vec![], page.page_size(), None, None)
//! .map(Json).map_err(|_| ApiProblem::internal_error())
//! }
//!
//! #[derive(utoipa::OpenApi)]
//! #[openapi(info(title = "Inventory API", version = "1.0.0"))]
//! struct Api;
//!
//! let (router, document, _) = OpenApiRouter::new(Api::openapi())?
//! .route(route!(items)?.with_cursor_pagination(PageLimits::new(20, 50)?)?)?
//! .into_parts();
//! let json = document.to_pretty_json()?;
//! // Export JSON or mount it on a route with application-specific access control.
//! # let _: Router = router;
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! [`annotate_contracts`] adds versioned `x-footing-contract` metadata after
//! checking exact method/path coverage and pagination/idempotency parameter
//! declarations. With footing's middleware stack, attach contracts using
//! [`OpenApiRoute::with_contract`]. Its callback receives each method and returns
//! an [`crate::http::EndpointPolicy`]; route identity and pagination are derived
//! automatically. Pagination can be configured before or after the policies.
//! Finish with
//! [`OpenApiRouter::into_parts_with_stack`] to validate and annotate the actual
//! registered routes together. Use [`crate::http::HttpAuthorizationHook`] to enforce
//! current access before idempotency replay; replayable contracts restricting
//! identity categories or declaring permissions require this hook. Contract metadata
//! itself does not enforce authorization or infer authentication schemes, response
//! codes, or business schemas. Validate
//! the documented application routes before adding a documentation endpoint.
//! Explicit GET registrations are checked as GET; Axum's automatic HEAD handling
//! does not require a separate contract unless HEAD is explicitly documented.
//!
//! # Runnable examples
//!
//! From a source checkout, export a specification or serve an embedded UI:
//!
//! ```sh
//! cargo run --example openapi --features openapi > openapi.json
//! cargo run --example docs --features rapidoc-embedded -- rapidoc
//! ```
//!
//! The documentation server listens on `http://127.0.0.1:3000/docs/` and serves
//! its specification at `/docs/openapi.json`. For ReDoc, use
//! `--features redoc-embedded -- redoc` instead.
//! If the example's UI argument is omitted, it prefers RapiDoc when that bundle
//! is enabled. This command-line fallback belongs to the example, not the library.
pub use crateopenapi_route as route;
pub use ;
pub use EMBEDDED_RAPIDOC_VERSION;
pub use EMBEDDED_REDOC_VERSION;
pub use ;
pub use ;
pub use problem_response;
pub use ;
/// OpenAPI schemas, document types, and derive macros used by this integration.
pub use utoipa;
/// ReDoc rendering and native Axum integration, included with OpenAPI support.
///
/// This re-export provides an alternative page API; it does not make ReDoc the
/// default renderer for [`OpenApiDocs`].
///
/// Mount the UI and specification together so application middleware can protect
/// both routes. Loading the specification from a URL keeps document descriptions
/// out of the HTML's inline script. Route and specification URLs are trusted
/// application configuration.
///
/// The default template loads ReDoc JavaScript and fonts from external hosts,
/// even when `redoc-embedded` is enabled. That feature supplies assets for
/// `DocsUi::embedded_redoc()`, without changing this native API's template.
/// Use [`redoc::Redoc::custom_html`] to select self-hosted assets or adapt the
/// template to an application's Content Security Policy.
///
/// ```rust
/// use axum::{Json, Router, routing::get};
/// use footing::http::openapi::{utoipa, redoc::{Redoc, Servable}};
/// use utoipa::OpenApi;
///
/// #[derive(utoipa::OpenApi)]
/// #[openapi(info(title = "Example API", version = "1.0.0"))]
/// struct Api;
///
/// let document = Api::openapi();
/// let docs: Router = Router::new()
/// .route("/openapi.json", get(move || {
/// let document = document.clone();
/// async move { Json(document) }
/// }))
/// .merge(Redoc::with_url("/docs", "/openapi.json"));
/// // Apply access-control middleware to `docs` before merging it into the app.
/// let app = Router::new().merge(docs);
/// # let _: Router = app;
/// ```
pub use utoipa_redoc as redoc;