footing 0.6.6

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`], field violations, 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.
//!
//! `openapi` enables only the HTTP foundations and document tooling. Enable
//! `pagination` for cursor/offset schemas, query parameters, and the route methods
//! `with_cursor_pagination` and `with_offset_pagination`, which install runtime
//! limits and update the document together. Enable `http-stack` for middleware
//! assembly, health responses, idempotency parameters, and checked
//! `OpenApiRouter::into_parts_with_stack` integration.
//!
//! ```rust
//! use axum::{Json, Router};
//! use footing::http::{ApiProblem, openapi::{OpenApiRouter, route, utoipa}};
//! use utoipa::OpenApi;
//!
//! #[derive(serde::Serialize, utoipa::ToSchema)]
//! struct Item { id: u64 }
//!
//! #[utoipa::path(get, path = "/items", responses(
//!     (status = 200, body = Vec<Item>),
//!     (status = 400, response = inline(ApiProblem))
//! ))]
//! async fn items() -> Result<Json<Vec<Item>>, ApiProblem> {
//!     Ok(Json(vec![]))
//! }
//!
//! #[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_api_fallbacks()
//!     .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>>(())
//! ```
//!
//! 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` (`http-stack`) to validate
//! documented policies against routes and middleware without exporting metadata.
//! Use `HttpAuthorizationHook` (`http-stack`) to enforce current access before
//! idempotency replay; replayable contracts restricting identity categories or
//! declaring permissions require this hook. 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.
//!
//! [`annotate_contracts`] explicitly exports versioned `x-footing-contract`
//! metadata after checking exact method/path coverage and pagination/idempotency
//! parameter declarations. This identifies footing and exposes permission
//! identifiers and operational policies; use it only for documents intended to
//! include that information. Route registration and middleware validation do not
//! add this metadata. Metadata itself does not enforce authorization or infer
//! authentication schemes, response codes, or business schemas.
//!
//! # Runnable examples
//!
//! From a source checkout, export a specification or serve an embedded UI:
//!
//! ```sh
//! cargo run --example openapi --features openapi,http-stack > openapi.json
//! cargo run --example docs --features rapidoc-embedded,http-stack -- 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,http-stack -- 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};
#[cfg(feature = "http-stack")]
pub use parameters::idempotency_key_parameter;
#[cfg(feature = "pagination")]
pub use parameters::{cursor_pagination_parameters, 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;