Trait ApiOperationResponse

Source

pub trait ApiOperationResponse {
    // Provided method
    fn api_operation_responses(
        operation: &mut Operation,
        route_context: &RouteContext<'_>,
        schema_generator: &mut SchemaGenerator,
    ) -> Vec<(Option<StatusCode>, Response)> { ... }
}

Available on crate feature openapi only.

Expand description

A trait that generates OpenAPI response objects for handler return types.

This trait is implemented for types that can be returned from request handlers and need to be documented in the OpenAPI specification. It allows you to specify how a type should be represented in the OpenAPI documentation.

§Examples

use cot::aide::openapi::{MediaType, Operation, Response, StatusCode};
use cot::openapi::{ApiOperationResponse, RouteContext};
use indexmap::IndexMap;
use schemars::SchemaGenerator;

// A custom response type
struct MyResponse<T>(T);

impl<T: schemars::JsonSchema> ApiOperationResponse for MyResponse<T> {
    fn api_operation_responses(
        _operation: &mut Operation,
        _route_context: &RouteContext<'_>,
        schema_generator: &mut SchemaGenerator,
    ) -> Vec<(Option<StatusCode>, Response)> {
        vec![(
            Some(StatusCode::Code(201)),
            Response {
                description: "Created".to_string(),
                content: IndexMap::from([(
                    "application/json".to_string(),
                    MediaType {
                        schema: Some(aide::openapi::SchemaObject {
                            json_schema: T::json_schema(schema_generator),
                            external_docs: None,
                            example: None,
                        }),
                        ..Default::default()
                    },
                )]),
                ..Default::default()
            },
        )]
    }
}

Provided Methods§

Source

fn api_operation_responses( operation: &mut Operation, route_context: &RouteContext<'_>, schema_generator: &mut SchemaGenerator, ) -> Vec<(Option<StatusCode>, Response)>

Returns a list of OpenAPI response objects for this type.

This method is called by the framework when generating the OpenAPI specification for a route. It should return a list of responses that this type can produce, along with their status codes.

The status code can be None to indicate a default response.

§Examples

use cot::aide::openapi::{MediaType, Operation, Response, StatusCode};
use cot::openapi::{ApiOperationResponse, RouteContext};
use indexmap::IndexMap;
use schemars::SchemaGenerator;

// A custom response type that always returns 201 Created
struct CreatedResponse<T>(T);

impl<T: schemars::JsonSchema> ApiOperationResponse for CreatedResponse<T> {
    fn api_operation_responses(
        _operation: &mut Operation,
        _route_context: &RouteContext<'_>,
        schema_generator: &mut SchemaGenerator,
    ) -> Vec<(Option<StatusCode>, Response)> {
        vec![(
            Some(StatusCode::Code(201)),
            Response {
                description: "Created".to_string(),
                content: IndexMap::from([(
                    "application/json".to_string(),
                    MediaType {
                        schema: Some(aide::openapi::SchemaObject {
                            json_schema: T::json_schema(schema_generator),
                            external_docs: None,
                            example: None,
                        }),
                        ..Default::default()
                    },
                )]),
                ..Default::default()
            },
        )]
    }
}