Struct OpenApi 

pub struct OpenApi { /* private fields */ }

The settings of an OpenAPI document, such as the API’s title and version.

Call generate with a router to create the document for its documented routes. For example, a route can serve it:

use topcoat::{
    Result,
    context::Cx,
    openapi::{Document, OpenApi},
    router::{route, router},
};

#[route(GET "/openapi.json")]
async fn spec(cx: &Cx) -> Result<Document> {
    Ok(OpenApi::new("Acme API", "1.0.0")
        .description("Everything you need for tea.")
        .generate(&router(cx)))
}

See Operation for documenting routes.

Implementations

impl OpenApi

pub fn new( title: impl Into<Cow<'static, str>>, version: impl Into<Cow<'static, str>>, ) -> Self

Creates the settings for an API with the given title and version.

The version is that of the API itself, such as 1.0.0.

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

Sets a description of the API as a whole.

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

Adds a base URL the API is reachable at, such as https://api.example.com.

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

Describes a tag that operations use.

Documentation tools show the description next to the tag’s routes and list tags in the order they are described here.

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

Registers a way for clients to authenticate under name.

Operations require it by that name with Operation::security.

pub fn generate(&self, router: &Router) -> Document

Creates the document for the documented routes of router.

A route is documented when an Operation is attached to it, to a layer or layout that wraps it, or to the router builder, unless the operation is hidden.

Panics

Panics when the routes are documented inconsistently:

• An operation describes a path parameter that its route’s path does not have.
• An operation requires a security scheme that is not registered.
• Two operations share an operation ID.
• A type passed to Operation::query is not a struct with named fields.

Trait Implementations

impl Clone for OpenApi

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 OpenApi

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

Formats the value using the given formatter.