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
//! Optional OpenAPI 3.1 support for Axum services.
//!
//! Enable the `openapi` feature to use the re-exported [`utoipa`] crate and
//! [`redoc`] for API documentation pages.
//! 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.
//!
//! [`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, false, 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. It 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.
pub use crateopenapi_route as route;
pub use ;
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.
///
/// 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.
/// 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;