Struct ApiDocBuilder 

pub struct ApiDocBuilder { /* private fields */ }

Builder for an ApiDoc.

Typical use:

use doxa::ApiDocBuilder;
use utoipa_axum::router::OpenApiRouter;

let (router, openapi) = OpenApiRouter::<()>::new().split_for_parts();

let api_doc = ApiDocBuilder::new()
    .title("Example API")
    .version(env!("CARGO_PKG_VERSION"))
    .description("Example service")
    .server("/", "current host")
    .bearer_security("bearer")
    .merge(openapi)
    .build();

Implementations

impl ApiDocBuilder

pub fn new() -> Self

Construct an empty builder. Title, version, and at least one path (via Self::merge) should be supplied before Self::build.

pub fn title(self, title: impl Into<String>) -> Self

Set the API title that appears in the document’s info.title.

pub fn version(self, version: impl Into<String>) -> Self

Set the API version that appears in the document’s info.version. Conventionally env!("CARGO_PKG_VERSION").

pub fn description(self, description: impl Into<String>) -> Self

Set the API description that appears in the document’s info.description. Markdown is supported by most viewers.

pub fn contact_name(self, name: impl Into<String>) -> Self

Set the contact name on the document’s info.contact.

pub fn contact_email(self, email: impl Into<String>) -> Self

Set the contact email on the document’s info.contact.

pub fn contact_url(self, url: impl Into<String>) -> Self

Set the contact URL on the document’s info.contact.

pub fn license(self, name: impl Into<String>) -> Self

Set the license name on the document’s info.license.

pub fn license_url(self, url: impl Into<String>) -> Self

Set the license URL on the document’s info.license.

pub fn server( self, url: impl Into<String>, description: impl Into<String>, ) -> Self

Append a server entry. The first call sets the primary server; additional calls add alternates (staging, regional endpoints).

pub fn bearer_security(self, name: impl Into<String>) -> Self

Register an HTTP bearer security scheme under the given name, advertising the bearer format as JWT.

The name is what handlers reference in their security(...) blocks (e.g., security(("bearer" = []))). Use bearer_security_with_format to override the format (for example for opaque, introspection-based tokens).

pub fn bearer_security_with_format( self, name: impl Into<String>, bearer_format: impl Into<String>, ) -> Self

Register an HTTP bearer security scheme under the given name with an explicit bearerFormat value.

Use this when the bearer token format is not JWT — for example RFC 7662 opaque tokens validated by introspection, SAML bearer assertions, or a proprietary token format that clients should not attempt to decode locally.

pub fn security_scheme( self, name: impl Into<String>, scheme: SecurityScheme, ) -> Self

Register an arbitrary security scheme under the given name. Use this for OAuth flows, API keys, OpenID Connect, etc.

pub fn oauth2_security( self, name: impl Into<String>, flows: impl IntoIterator<Item = Flow>, ) -> Self

Register an OAuth2 security scheme under the given name with the supplied Flow entries.

Prefer this over Self::bearer_security when handlers declare per-operation scope requirements (e.g. via crate::DocOperationSecurity impls). The bearer-only HTTP scheme has no scope vocabulary, so OpenAPI client codegen (openapi-generator, oapi-codegen, etc.) silently drops any scopes attached to operation security entries. With an OAuth2 scheme that publishes the scope vocabulary in flows.<flow>.scopes, generated clients carry the required scopes through to the token request.

pub fn tag( self, name: impl Into<String>, description: impl Into<String>, ) -> Self

Register a tag with a display name and description. Tags are auto-discovered from operations at build time, so this is only needed when you want to override the description shown in the docs UI for a specific tag.

When provided, the tag’s position in the .tag() call order determines its display order in the sidebar. Auto-discovered tags without an explicit .tag() entry appear after any explicitly registered ones, sorted alphabetically.

pub fn tag_group( self, name: impl Into<String>, tags: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Manually group tags into a named section via the x-tagGroups vendor extension (Scalar + Redoc).

When any .tag_group() call is present, auto-grouping is disabled — the caller takes full control of the grouping. Tags not assigned to any group may be hidden by some renderers (notably Redoc).

When no .tag_group() calls are present, the builder auto-generates groups by splitting tag names on the delimiter (default ": "). For example, "Admin: Models" is placed in the "Admin" group. Tags without the delimiter go into the default group (see Self::default_tag_group).

pub fn default_tag_group(self, name: impl Into<String>) -> Self

Set the name of the default tag group for tags that don’t contain the group delimiter. Defaults to "API" when auto-grouping is active.

Only meaningful when no explicit .tag_group() calls are present (i.e., auto-grouping is active).

pub fn tag_group_delimiter(self, delimiter: impl Into<String>) -> Self

Set the delimiter used to split tag names into (group, display_name) for auto-generated tag groups. Defaults to ": ".

For example, with delimiter ": ", the tag "Admin: Models" is placed in the "Admin" group. With delimiter "/", the tag "Admin/Models" would be placed in the "Admin" group.

pub fn schema_tag( self, schema: impl Into<String>, tag: impl Into<String>, ) -> Self

Manually assign a tag to a schema. The tag is injected as an x-tags vendor extension on the schema in components.schemas. Manual tags merge with auto-inferred tags (schemas automatically inherit tags from the operations that reference them).

pub fn sse_openapi_version(self, version: SseSpecVersion) -> Self

Choose the OpenAPI spec version used to render text/event-stream responses produced by handlers returning crate::SseStream.

Defaults to SseSpecVersion::V3_2 — the rendered document will carry openapi: "3.2.0" and SSE responses will place the event schema under itemSchema, matching the OpenAPI 3.2 first-class SSE support. Call with SseSpecVersion::V3_1 to downgrade for consumers that still require the 3.1 shape (Redoc, openapi-generator, swagger-parser < 3.2).

Example

use doxa::{ApiDocBuilder, SseSpecVersion};

// Render against OpenAPI 3.1 for consumers that don't yet
// understand the 3.2 `itemSchema` keyword.
let doc = ApiDocBuilder::new()
    .title("Compat")
    .version("1.0.0")
    .sse_openapi_version(SseSpecVersion::V3_1)
    .build();

pub fn merge(self, openapi: OpenApi) -> Self

Merge an existing OpenApi (typically from utoipa_axum::router::OpenApiRouter::split_for_parts) into the document. The merged document inherits paths, components, and tags from the supplied value.

pub fn try_build(self) -> Result<ApiDoc, BuildError>

Finalize the builder, producing an ApiDoc with its JSON representation pre-serialized into an Arc<str>. Returns an error only if JSON serialization itself fails — which in practice requires a malformed custom schema to be present in the merged document.

pub fn build(self) -> ApiDoc

Convenience wrapper around Self::try_build that panics on serialization failure. Suitable for startup code where a failed build is unrecoverable.

Trait Implementations

impl Default for ApiDocBuilder

fn default() -> ApiDocBuilder

Returns the “default value” for a type.