Struct Operation 

pub struct Operation { /* private fields */ }

Describes a route in the API document.

Add it to a route with with(...). A route appears in the document when an Operation is attached to it or to a layer that wraps it:

use serde::{Deserialize, Serialize};
use topcoat::{
    Result,
    context::Cx,
    openapi::{Operation, schemars::JsonSchema},
    router::{Body, Next, StatusCode, content::Json, layer, response::Response, route},
};

#[derive(Deserialize, JsonSchema)]
struct CreateUser {
    name: String,
}

#[derive(Serialize, JsonSchema)]
struct User {
    id: u64,
    name: String,
}

// Every route under `/api` is documented and tagged.
#[layer("/api", with(Operation::new().tag("api")))]
async fn api(cx: &Cx, body: Body, next: Next<'_>) -> Result<Response> {
    next.run(cx, body).await
}

#[route(POST "/api/users", with(
    Operation::new()
        .summary("Create a user")
        .request::<Json<CreateUser>>()
        .response_with::<Json<User>>(StatusCode::CREATED, "The new user.")
))]
async fn create_user(
    cx: &Cx,
    Json(input): Json<CreateUser>,
) -> Result<(StatusCode, Json<User>)> {
    Ok((
        StatusCode::CREATED,
        Json(User {
            id: 1,
            name: input.name,
        }),
    ))
}

A route combines its own operation with those of its layers, and the closest value of each setting takes priority. Tags, parameters, and responses add up instead: a route keeps the ones its layers declare and replaces only a parameter or response status it declares itself.

Implementations

impl Operation

pub fn new() -> Self

Creates an operation that inherits every setting.

pub fn summary(self, summary: impl Into<Cow<'static, str>>) -> Self

Sets a short summary of what the route does.

pub fn description(self, description: impl Into<Cow<'static, str>>) -> Self

Sets a longer explanation of the route’s behavior.

pub fn operation_id(self, operation_id: impl Into<Cow<'static, str>>) -> Self

Sets the name that identifies the operation, which client generators use to name their functions.

An ID has to be unique in the document, so set it on a route that serves a single method rather than on a layer.

pub fn deprecated(self, deprecated: bool) -> Self

Marks the route as deprecated, so clients know to move away from it.

pub fn hidden(self, hidden: bool) -> Self

Chooses whether to leave the route out of the document.

Pass true to hide a route that a layer documents. Pass false to show a route below a layer that hides its routes.

pub fn tag(self, tag: impl Into<Cow<'static, str>>) -> Self

Adds a tag, which documentation tools use to group routes.

pub fn parameter(self, parameter: Parameter) -> Self

Describes a path, query, header, or cookie parameter.

Describing the same parameter again replaces the earlier entry.

pub fn query<T: JsonSchema>(self) -> Self

Documents every field of the struct T as a query parameter.

This suits a struct read with query_params. Optional fields become optional parameters, and doc comments on fields become their descriptions:

use topcoat::{
    openapi::{Operation, schemars::JsonSchema},
    router::query_params,
};

#[query_params]
#[derive(JsonSchema)]
struct PostsQuery {
    /// The page to show, starting at 1.
    page: Option<u32>,
}

let operation = Operation::new().query::<PostsQuery>();

pub fn request<T: Content>(self) -> Self

Documents the request body, for example .request::<Json<CreateUser>>().

Wrap the type in Option for a body that requests may leave out.

pub fn response( self, status: StatusCode, description: impl Into<Cow<'static, str>>, ) -> Self

Documents a response without a body, for example .response(StatusCode::NO_CONTENT, "The user was deleted.").

Declaring a status again replaces its earlier response.

pub fn response_with<T: Content>( self, status: StatusCode, description: impl Into<Cow<'static, str>>, ) -> Self

Documents a response with a body, for example .response_with::<Json<User>>(StatusCode::OK, "The user.").

Declaring a status again replaces its earlier response.

pub fn security(self, scheme: impl Into<Cow<'static, str>>) -> Self

Requires clients to authenticate with the security scheme registered under scheme.

Calling this again adds an alternative, so clients may use either scheme. The requirements of an operation replace those of its layers as a whole.

See OpenApi::security_scheme for registering a scheme.

pub fn no_security(self) -> Self

Documents the route as usable without authentication, even when a layer requires it.

Trait Implementations

impl Clone for Operation

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Operation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Operation

fn default() -> Self

Returns the “default value” for a type.