Struct OpenApi 

pub struct OpenApi { /* private fields */ }

An OpenAPI 3.1 document under construction.

Implementations

impl OpenApi

pub fn new(title: impl Into<String>, version: impl Into<String>) -> Self

A document for an API with this title and version.

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

Describe the API as a whole.

pub fn server(self, url: impl Into<String>, description: Option<&str>) -> Self

Add a server URL clients should send requests to.

pub fn from_routes(self, routes: &[(Method, String)]) -> Self

Seed the document from the router’s inventory.

Pass AppBuilder::routes after the application’s own routes are registered. Every route becomes an operation, whether or not it is described further.

pub fn operation(self, method: Method, path: &str, operation: Operation) -> Self

Attach a description to one route.

Describing a route that was never registered is allowed while building, and reported by stale rather than refused here, so a document can be assembled in any order.

pub fn undescribed(&self) -> Vec<(Method, String)>

Registered routes with no description attached.

use churust_core::{Call, Churust};
use churust_openapi::OpenApi;
use http::Method;

let builder = Churust::server().routing(|r| {
    r.get("/health", |_c: Call| async { "ok" });
});
let api = OpenApi::new("API", "1.0").from_routes(builder.routes());
assert_eq!(api.undescribed(), vec![(Method::GET, "/health".to_string())]);

pub fn stale(&self) -> Vec<(Method, String)>

Descriptions whose route no longer exists.

The direction of drift that actually misleads a client: a documented endpoint that answers 404.

pub fn to_value(&self) -> Value

Render the document as JSON.

pub fn mount(&self, routes: &mut RouteBuilder<'_>, path: &str)

Register a route serving this document as JSON.

Call it inside a routing block after the routes being described, so the inventory is complete:

let builder = Churust::server().routing(|r| {
    r.get("/health", |_c: Call| async { "ok" });
});
let api = OpenApi::new("API", "1.0").from_routes(builder.routes());
let app = builder.routing(|r| api.mount(r, "/openapi.json")).build();

The document is rendered once, here, rather than per request: it cannot change after the router is built.

Trait Implementations

impl Clone for OpenApi

fn clone(&self) -> OpenApi

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.