Struct OperationBuilder 

pub struct OperationBuilder<H = Missing, R = Missing, S = (), A = AuthNotSet, L = LicenseNotSet>
where
    H: HandlerSlot<S>,
    A: AuthState,
    L: LicenseState,
{ /* private fields */ }

Type-safe operation builder with compile-time guarantees.

Generic parameters:

• H: Handler state (Missing | Present)
• R: Response state (Missing | Present)
• S: Router state type (what you put into Router::with_state(S)).
• A: Auth state (AuthNotSet | AuthSet)
• L: License requirement state (LicenseNotSet | LicenseSet)

Implementations

impl<S> OperationBuilder<Missing, Missing, S, AuthNotSet>

pub fn new(method: Method, path: impl Into<String>) -> Self

Create a new operation builder with an HTTP method and path

pub fn get(path: impl Into<String>) -> Self

Convenience constructor for GET requests

pub fn post(path: impl Into<String>) -> Self

Convenience constructor for POST requests

pub fn put(path: impl Into<String>) -> Self

Convenience constructor for PUT requests

pub fn delete(path: impl Into<String>) -> Self

Convenience constructor for DELETE requests

pub fn patch(path: impl Into<String>) -> Self

Convenience constructor for PATCH requests

impl<H, R, S, A, L> OperationBuilder<H, R, S, A, L>

where H: HandlerSlot<S>, A: AuthState, L: LicenseState,

pub fn spec(&self) -> &OperationSpec

Inspect the spec (primarily for tests)

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

Set the operation ID

pub fn require_rate_limit( &mut self, rps: u32, burst: u32, in_flight: u32, ) -> &mut Self

Require per-route rate and concurrency limits. Stores metadata for the gateway to enforce.

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

Set the operation summary

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

Set the operation description

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

Add a tag to the operation

pub fn param(self, param: ParamSpec) -> Self

Add a parameter to the operation

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

Add a path parameter with type inference (defaults to string)

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

Add a query parameter (defaults to string)

pub fn query_param_typed( self, name: impl Into<String>, required: bool, description: impl Into<String>, param_type: impl Into<String>, ) -> Self

Add a typed query parameter with explicit OpenAPI type

pub fn json_request_schema( self, schema_name: impl Into<String>, desc: impl Into<String>, ) -> Self

Attach a JSON request body by schema name that you’ve already registered. This variant sets a description (Some(desc)) and marks the body as required.

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

Attach a JSON request body by schema name with no description (None). Marks the body as required.

pub fn json_request<T>( self, registry: &dyn OpenApiRegistry, desc: impl Into<String>, ) -> Self

where T: ToSchema + PartialSchema + RequestApiDto + 'static,

Attach a JSON request body and auto-register its schema using utoipa. This variant sets a description (Some(desc)) and marks the body as required.

pub fn json_request_no_desc<T>(self, registry: &dyn OpenApiRegistry) -> Self

where T: ToSchema + PartialSchema + RequestApiDto + 'static,

Attach a JSON request body (auto-register schema) with no description (None). Marks the body as required.

pub fn request_optional(self) -> Self

Make the previously attached request body optional (if any).

pub fn multipart_file_request( self, field_name: &str, description: Option<&str>, ) -> Self

Configure a multipart/form-data file upload request.

This is a convenience helper for file upload endpoints that:

• Sets the request body content type to “multipart/form-data”
• Sets a description for the request body
• Configures an inline object schema with a binary file field
• Restricts allowed Content-Type to only “multipart/form-data”

The file field will be documented in OpenAPI as a binary string with the given field name. This generates the correct OpenAPI schema for UI tools like Stoplight to display a file upload control.

Arguments

• field_name - Name of the multipart form field (e.g., “file”)
• description - Optional description for the request body

Example

let router = OperationBuilder::post("/files/v1/upload")
    .operation_id("upload_file")
    .summary("Upload a file")
    .multipart_file_request("file", Some("File to upload"))
    .public()
    .handler(upload_handler)
    .json_response(StatusCode::OK, "Upload successful")
    .register(router, &registry);

pub fn octet_stream_request(self, description: Option<&str>) -> Self

Configure the request body as raw binary (application/octet-stream).

This is intended for endpoints that accept the entire request body as a file or arbitrary bytes, without multipart form encoding.

The OpenAPI schema will be:

requestBody:
  required: true
  content:
    application/octet-stream:
      schema:
        type: string
        format: binary

Tools like Stoplight will render this as a single file upload control for the entire body.

Arguments

• description - Optional description for the request body

Example

let router = OperationBuilder::post("/files/v1/upload")
    .operation_id("upload_file")
    .summary("Upload a file")
    .octet_stream_request(Some("Raw file bytes to parse"))
    .public()
    .handler(upload_handler)
    .json_response(StatusCode::OK, "Upload successful")
    .register(router, &registry);

pub fn allow_content_types(self, types: &[&'static str]) -> Self

Configure allowed request MIME types for this operation.

This attaches a whitelist of allowed Content-Type values (without parameters), which will be enforced by gateway middleware. If a request arrives with a Content-Type that is not in this list, gateway will return HTTP 415.

This is independent of the request body schema - it only configures gateway validation and does not affect OpenAPI request body specifications.

Example

let router = OperationBuilder::post("/files/v1/upload")
    .operation_id("upload_file")
    .allow_content_types(&["multipart/form-data", "application/pdf"])
    .public()
    .handler(upload_handler)
    .json_response(StatusCode::OK, "Upload successful")
    .register(router, &registry);

impl<H, R, S> OperationBuilder<H, R, S, AuthSet, LicenseNotSet>

where H: HandlerSlot<S>,

License requirement setting — transitions LicenseNotSet -> LicenseSet

pub fn require_license_features<F>( self, licenses: impl IntoIterator<Item = F>, ) -> OperationBuilder<H, R, S, AuthSet, LicenseSet>

where F: LicenseFeature,

Set (or explicitly clear) the license feature requirement for this operation.

This method is only available after the auth requirement has been decided (i.e. after calling authenticated()).

Mandatory for authenticated endpoints: operations configured with authenticated() must call require_license_features(...) before register(), because register() is only available once the license requirement state has transitioned to LicenseSet.

Not available for public endpoints: public routes cannot (and do not need to) call this method.

Pass an empty iterator (e.g. []) to explicitly declare that no license feature is required.

pub fn no_license_required( self, ) -> OperationBuilder<H, R, S, AuthSet, LicenseSet>

Explicitly declare that this operation does not require any license.

Use this for system/infrastructure endpoints that need authentication but are not gated behind application-level license features.

This transitions from LicenseNotSet to LicenseSet without attaching any license requirement.

impl<H, R, S, L> OperationBuilder<H, R, S, AuthNotSet, L>

where H: HandlerSlot<S>, L: LicenseState,

pub fn authenticated(self) -> OperationBuilder<H, R, S, AuthSet, L>

Mark this route as requiring authentication.

This is a binary marker — the route requires a valid bearer token. Scope enforcement (which scopes are needed) is configured at the gateway level, not per-route.

This method transitions from AuthNotSet to AuthSet state.

Example

enum License {
    Base,
}

impl AsRef<str> for License {
    fn as_ref(&self) -> &str {
        match self {
            License::Base => "gts.x.core.lic.feat.v1~x.core.global.base.v1",
        }
    }
}

impl LicenseFeature for License {}

let router = OperationBuilder::get("/users-info/v1/users")
    .authenticated()
    .require_license_features::<License>([])
    .handler(list_users_handler)
    .json_response(axum::http::StatusCode::OK, "List of users")
    .register(router, api);

pub fn public(self) -> OperationBuilder<H, R, S, AuthSet, LicenseSet>

Mark this route as public (no authentication required).

This explicitly opts out of the require_auth_by_default setting. This method transitions from AuthNotSet to AuthSet state.

Example

let router = OperationBuilder::get("/users-info/v1/health")
    .public()
    .handler(health_check)
    .json_response(StatusCode::OK, "OK")
    .register(router, &registry);

impl<R, S, A, L> OperationBuilder<Missing, R, S, A, L>

where S: Clone + Send + Sync + 'static, A: AuthState, L: LicenseState,

pub fn handler<F, T>(self, h: F) -> OperationBuilder<Present, R, S, A, L>

where F: Handler<T, S> + Clone + Send + 'static, T: 'static,

Set the handler for this operation (function handlers are recommended).

This transitions the builder from Missing to Present handler state.

pub fn method_router( self, mr: MethodRouter<S>, ) -> OperationBuilder<Present, R, S, A, L>

Alternative path: provide a pre-composed MethodRouter<S> yourself (useful to attach per-route middleware/layers).

impl<H, S, A, L> OperationBuilder<H, Missing, S, A, L>

where H: HandlerSlot<S>, A: AuthState, L: LicenseState,

pub fn response( self, resp: ResponseSpec, ) -> OperationBuilder<H, Present, S, A, L>

Add a raw response spec (transitions from Missing to Present).

pub fn json_response( self, status: StatusCode, description: impl Into<String>, ) -> OperationBuilder<H, Present, S, A, L>

Add a JSON response (transitions from Missing to Present).

pub fn json_response_with_schema<T>( self, registry: &dyn OpenApiRegistry, status: StatusCode, description: impl Into<String>, ) -> OperationBuilder<H, Present, S, A, L>

where T: ToSchema + PartialSchema + ResponseApiDto + 'static,

Add a JSON response with a registered schema (transitions from Missing to Present).

pub fn text_response( self, status: StatusCode, description: impl Into<String>, content_type: &'static str, ) -> OperationBuilder<H, Present, S, A, L>

Add a text response with a custom content type (transitions from Missing to Present).

Arguments

• status - HTTP status code
• description - Description of the response
• content_type - Pure media type without parameters (e.g., "text/plain", "text/markdown")

Important

The content_type must be a pure media type without parameters like ; charset=utf-8. OpenAPI media type keys cannot include parameters. Use "text/markdown" instead of "text/markdown; charset=utf-8". Actual HTTP response headers in handlers should still include the charset parameter.

pub fn html_response( self, status: StatusCode, description: impl Into<String>, ) -> OperationBuilder<H, Present, S, A, L>

Add an HTML response (transitions from Missing to Present).

pub fn problem_response( self, registry: &dyn OpenApiRegistry, status: StatusCode, description: impl Into<String>, ) -> OperationBuilder<H, Present, S, A, L>

Add an RFC 9457 application/problem+json response (transitions from Missing to Present).

pub fn sse_json<T>( self, openapi: &dyn OpenApiRegistry, description: impl Into<String>, ) -> OperationBuilder<H, Present, S, A, L>

where T: ToSchema + PartialSchema + ResponseApiDto + 'static,

First response: SSE stream of JSON events (text/event-stream).

impl<H, S, A, L> OperationBuilder<H, Present, S, A, L>

where H: HandlerSlot<S>, A: AuthState, L: LicenseState,

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

Add a JSON response (additional).

pub fn json_response_with_schema<T>( self, registry: &dyn OpenApiRegistry, status: StatusCode, description: impl Into<String>, ) -> Self

where T: ToSchema + PartialSchema + ResponseApiDto + 'static,

Add a JSON response with a registered schema (additional).

pub fn text_response( self, status: StatusCode, description: impl Into<String>, content_type: &'static str, ) -> Self

Add a text response with a custom content type (additional).

Arguments

• status - HTTP status code
• description - Description of the response
• content_type - Pure media type without parameters (e.g., "text/plain", "text/markdown")

Important

The content_type must be a pure media type without parameters like ; charset=utf-8. OpenAPI media type keys cannot include parameters. Use "text/markdown" instead of "text/markdown; charset=utf-8". Actual HTTP response headers in handlers should still include the charset parameter.

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

Add an HTML response (additional).

pub fn problem_response( self, registry: &dyn OpenApiRegistry, status: StatusCode, description: impl Into<String>, ) -> Self

Add an additional RFC 9457 application/problem+json response.

pub fn sse_json<T>( self, openapi: &dyn OpenApiRegistry, description: impl Into<String>, ) -> Self

where T: ToSchema + PartialSchema + ResponseApiDto + 'static,

Additional SSE response (if the operation already has a response).

pub fn standard_errors(self, registry: &dyn OpenApiRegistry) -> Self

Add standard error responses (400, 401, 403, 404, 409, 422, 429, 500).

All responses reference the shared Problem schema (RFC 9457) for consistent error handling across your API. This is the recommended way to declare common error responses without repeating boilerplate.

Example

let op = OperationBuilder::get("/user-info/v1/users")
    .public()
    .handler(list_users)
    .json_response(StatusCode::OK, "List of users")
    .standard_errors(&registry);

let router = op.register(router, &registry);

This adds the following error responses:

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 409 Conflict
• 422 Unprocessable Entity
• 429 Too Many Requests
• 500 Internal Server Error

pub fn with_422_validation_error(self, registry: &dyn OpenApiRegistry) -> Self

Add 422 validation error response using ValidationError schema.

This method adds a specific 422 Unprocessable Entity response that uses the ValidationError schema instead of the generic Problem schema. Use this for endpoints that perform input validation and need structured error details.

Example

#[modkit_macros::api_dto(request)]
struct CreateUserRequest {
    email: String,
}

let op = OperationBuilder::post("/users-info/v1/users")
    .public()
    .handler(create_user)
    .json_request::<CreateUserRequest>(&registry, "User data")
    .json_response(StatusCode::CREATED, "User created")
    .with_422_validation_error(&registry);

let router = op.register(router, &registry);

pub fn error_400(self, registry: &dyn OpenApiRegistry) -> Self

Add a 400 Bad Request error response.

This is a convenience wrapper around problem_response.

pub fn error_401(self, registry: &dyn OpenApiRegistry) -> Self

Add a 401 Unauthorized error response.

This is a convenience wrapper around problem_response.

pub fn error_403(self, registry: &dyn OpenApiRegistry) -> Self

Add a 403 Forbidden error response.

This is a convenience wrapper around problem_response.

pub fn error_404(self, registry: &dyn OpenApiRegistry) -> Self

Add a 404 Not Found error response.

This is a convenience wrapper around problem_response.

pub fn error_409(self, registry: &dyn OpenApiRegistry) -> Self

Add a 409 Conflict error response.

This is a convenience wrapper around problem_response.

pub fn error_415(self, registry: &dyn OpenApiRegistry) -> Self

Add a 415 Unsupported Media Type error response.

This is a convenience wrapper around problem_response.

pub fn error_422(self, registry: &dyn OpenApiRegistry) -> Self

Add a 422 Unprocessable Entity error response.

This is a convenience wrapper around problem_response.

pub fn error_429(self, registry: &dyn OpenApiRegistry) -> Self

Add a 429 Too Many Requests error response.

This is a convenience wrapper around problem_response.

pub fn error_500(self, registry: &dyn OpenApiRegistry) -> Self

Add a 500 Internal Server Error response.

This is a convenience wrapper around problem_response.

impl<S> OperationBuilder<Present, Present, S, AuthSet, LicenseSet>

where S: Clone + Send + Sync + 'static,

pub fn register( self, router: Router<S>, openapi: &dyn OpenApiRegistry, ) -> Router<S>

Register the operation with the router and OpenAPI registry.

This method is only available when:

• Handler is present
• Response is present
• Auth requirement is set (either authenticated or public)

All conditions are enforced at compile time by the type system.

Trait Implementations

impl<S, H, R, A, L> OperationBuilderODataExt<S, H, R> for OperationBuilder<H, R, S, A, L>

where H: HandlerSlot<S>, A: AuthState, L: LicenseState,

fn with_odata_filter<T>(self) -> Self

where T: FilterField,

Adds optional $filter query parameter to OpenAPI.

fn with_odata_select(self) -> Self

Adds optional $select query parameter to OpenAPI.

fn with_odata_orderby<T>(self) -> Self

where T: FilterField,

Adds optional $orderby query parameter to OpenAPI.