footing 0.1.19

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.
//! 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.

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