footing 0.5.5

Feature-gated foundations for Rust backend services
Documentation
//! 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.

mod contracts;
mod docs;
mod parameters;
mod responses;
mod router;
mod schemas;

pub use crate::openapi_route as route;
pub use contracts::{
    CONTRACT_EXTENSION, OpenApiContractError, annotate_contracts, validate_contracts,
};
#[cfg(feature = "rapidoc-embedded")]
pub use docs::EMBEDDED_RAPIDOC_VERSION;
#[cfg(feature = "redoc-embedded")]
pub use docs::EMBEDDED_REDOC_VERSION;
pub use docs::{DocsAssets, DocsError, DocsUi, OpenApiDocs};
pub use parameters::{
    cursor_pagination_parameters, idempotency_key_parameter, offset_pagination_parameters,
};
pub use responses::problem_response;
pub use router::{OpenApiRoute, OpenApiRouteError, OpenApiRouter};

/// 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;