Crate baukit_openapi 

Small, product-neutral helpers for consistent OpenAPI documents.

Products continue to own paths, operations, and endpoint schemas. This crate only applies Baukit’s document conventions, provides the shared error envelope schema, documents error responses from product rules, offers opt-in bearer authentication metadata, manages a deterministic committed schema, and checks that property and parameter names are camelCase.

Example

use baukit_openapi::{ErrorEnvelope, OpenApiMetadata, serialize_schema};
use utoipa::openapi::Server;

#[derive(utoipa::OpenApi)]
#[openapi(components(schemas(ErrorEnvelope)))]
struct ApiDoc;

let mut document = <ApiDoc as utoipa::OpenApi>::openapi();
OpenApiMetadata::new("Orders API", "1.2.3", "The Orders service API")
    .servers([Server::new("https://api.example.com")])
    .apply_to(&mut document);

let json = serialize_schema(&document)?;
assert!(json.ends_with('\n'));

Structs

ErrorBody

The error body nested inside ErrorEnvelope.

ErrorEnvelope

The shared public error response envelope.

ErrorResponseRules

Error responses and response headers to document on every matching operation, as data.

NamingViolation

A property or parameter name that is not camelCase.

OpenApiMetadata

Baukit document metadata and optional security conventions.

ResponseEnvelope

A fully typed success-response envelope.

Rfc3339DateTime

An API timestamp with one JSON and OpenAPI representation: an RFC 3339 string with OpenAPI date-time format.

SchemaError

An error produced while serializing, writing, comparing, or naming-checking an OpenAPI schema.

Enums

IfMatchRequirement

Whether a route rejects a write that omits If-Match.

NameKind

The kind of name a NamingViolation refers to.

OperationCondition

A property of an operation that decides whether a rule applies to it.

ResponseSelector

Which responses of a matching operation a header rule documents.

Constants

BEARER_AUTH_SCHEME

The component name used for Baukit’s standard HTTP bearer JWT security scheme.

ETAG_HEADER

The response header that carries a strong revision validator.

IF_MATCH_HEADER

The request header that carries a revision precondition.

INVALID_IF_MATCH_CODE

Error code for an If-Match value that is not one strong ETag for the resource (HTTP 400).

PRECONDITION_FAILED_CODE

Error code for an If-Match revision that is no longer current (HTTP 412).

PRECONDITION_REQUIRED_CODE

Error code for a required If-Match header that is missing (HTTP 428).

REQUEST_ID_HEADER

The response header that carries the request identifier.

RETRY_AFTER_HEADER

The response header that tells a client how many seconds to wait before retrying.

WWW_AUTHENTICATE_HEADER

The response header that carries an authentication challenge.

Functions

assert_camel_case_names

Asserts that every property and parameter name in a document is camelCase.

assert_no_drift

Asserts that a committed schema exactly matches deterministic serialization of the document.

check_camel_case_names

Checks that every property and parameter name in a document is camelCase.

check_no_drift

Checks that a committed schema exactly matches deterministic serialization of the document.

document_etag

Documents the ETag header on every inline 2xx response of one operation.

document_if_match

Documents a revision precondition on one operation.

etag_header

Returns the documented ETag response header for a strong revision validator.

fill_missing_response_descriptions

Fills empty response descriptions so utoipa emits OpenAPI’s required field.

find_naming_violations

Finds every property and parameter name in a serialized OpenAPI document that is not camelCase.

if_match_parameter

Returns the documented If-Match header parameter for a revision precondition.

is_camel_case

Returns true for a lower camelCase name: an ASCII lowercase letter followed by ASCII letters and digits.

request_id_header

Returns the documented X-Request-Id response header.

retry_after_header

Returns the documented Retry-After response header in delta seconds.

serialize_schema

Serializes an OpenAPI document as deterministically ordered pretty JSON with a trailing newline.

write_schema

Writes a deterministic schema atomically, creating parent directories when necessary.

www_authenticate_header

Returns the documented WWW-Authenticate response header for a bearer challenge.