Struct utoipa_swagger_ui::SwaggerUi

#[non_exhaustive]
pub struct SwaggerUi { /* private fields */ }

Available on crate features actix-web or rocket or axum only.

Entry point for serving Swagger UI and api docs in application. It provides builder style chainable configuration methods for configuring api doc urls.

Examples

Create new SwaggerUi with defaults.

let swagger = SwaggerUi::new("/swagger-ui/{_:.*}")
    .url("/api-docs/openapi.json", ApiDoc::openapi());

Create a new SwaggerUi with custom Config and oauth::Config.

let swagger = SwaggerUi::new("/swagger-ui/{_:.*}")
    .url("/api-docs/openapi.json", ApiDoc::openapi())
    .config(Config::default().try_it_out_enabled(true).filter(true))
    .oauth(oauth::Config::new());

Implementations

impl SwaggerUi

pub fn new<P: Into<Cow<'static, str>>>(path: P) -> Self

Create a new SwaggerUi for given path.

Path argument will expose the Swagger UI to the user and should be something that the underlying application framework / library supports.

Examples

Exposes Swagger UI using path /swagger-ui using actix-web supported syntax.

let swagger = SwaggerUi::new("/swagger-ui/{_:.*}");

pub fn url<U: Into<Url<'static>>>(self, url: U, openapi: OpenApi) -> Self

Add api doc Url into SwaggerUi.

Method takes two arguments where first one is path which exposes the OpenApi to the user. Second argument is the actual Rust implementation of the OpenAPI doc which is being exposed.

Calling this again will add another url to the Swagger UI.

Examples

Expose manually created OpenAPI doc.

let swagger = SwaggerUi::new("/swagger-ui/{_:.*}")
    .url("/api-docs/openapi.json", utoipa::openapi::OpenApi::new(
       utoipa::openapi::Info::new("my application", "0.1.0"),
       utoipa::openapi::Paths::new(),
));

Expose derived OpenAPI doc.

let swagger = SwaggerUi::new("/swagger-ui/{_:.*}")
    .url("/api-docs/openapi.json", ApiDoc::openapi());

pub fn urls(self, urls: Vec<(Url<'static>, OpenApi)>) -> Self

Add multiple Urls to Swagger UI.

Takes one Vec argument containing tuples of Url and OpenApi.

Situations where this comes handy is when there is a need or wish to separate different parts of the api to separate api docs.

Examples

Expose multiple api docs via Swagger UI.

let swagger = SwaggerUi::new("/swagger-ui/{_:.*}")
    .urls(
      vec![
         (Url::with_primary("api doc 1", "/api-docs/openapi.json", true), ApiDoc::openapi()),
         (Url::new("api doc 2", "/api-docs/openapi2.json"), ApiDoc2::openapi())
    ]
);

pub fn external_url_unchecked<U: Into<Url<'static>>>( self, url: U, openapi: Value ) -> Self

Add external API doc to the SwaggerUi.

This operation is unchecked and so it does not check any validity of provided content. Users are required to do their own check if any regarding validity of the external OpenAPI document.

Method accepts two arguments, one is Url the API doc is served at and the second one is the serde_json::Value of the OpenAPI doc to be served.

Examples

Add external API doc to the SwaggerUi.

let external_openapi = json!({"openapi": "3.0.0"});

let swagger = SwaggerUi::new("/swagger-ui/{_:.*}")
    .external_url_unchecked("/api-docs/openapi.json", external_openapi);

pub fn external_urls_from_iter_unchecked<I: IntoIterator<Item = (U, Value)>, U: Into<Url<'static>>>( self, external_urls: I ) -> Self

Add external API docs to the SwaggerUi from iterator.

This operation is unchecked and so it does not check any validity of provided content. Users are required to do their own check if any regarding validity of the external OpenAPI documents.

Method accepts one argument, an iter of Url and serde_json::Value tuples. The Url will point to location the OpenAPI document is served and the serde_json::Value is the OpenAPI document to be served.

Examples

Add external API docs to the SwaggerUi.

let external_openapi = json!({"openapi": "3.0.0"});
let external_openapi2 = json!({"openapi": "3.0.0"});

let swagger = SwaggerUi::new("/swagger-ui/{_:.*}")
    .external_urls_from_iter_unchecked([
        ("/api-docs/openapi.json", external_openapi),
        ("/api-docs/openapi2.json", external_openapi2)
    ]);

pub fn oauth(self, oauth: Config) -> Self

Add oauth oauth::Config into SwaggerUi.

Method takes one argument which exposes the oauth::Config to the user.

Examples

Enable pkce with default client_id.

let swagger = SwaggerUi::new("/swagger-ui/{_:.*}")
    .url("/api-docs/openapi.json", ApiDoc::openapi())
    .oauth(oauth::Config::new()
        .client_id("client-id")
        .scopes(vec![String::from("openid")])
        .use_pkce_with_authorization_code_grant(true)
    );

pub fn config(self, config: Config<'static>) -> Self

Add custom Config into SwaggerUi which gives users more granular control over Swagger UI options.

Methods takes one Config argument which exposes Swagger UI’s configurable options to the users.

Examples

Create a new SwaggerUi with custom configuration.

let swagger = SwaggerUi::new("/swagger-ui/{_:.*}")
    .url("/api-docs/openapi.json", ApiDoc::openapi())
    .config(Config::default().try_it_out_enabled(true).filter(true));

Trait Implementations

impl Clone for SwaggerUi

fn clone(&self) -> SwaggerUi

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<S> From<SwaggerUi> for Router<S>

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

fn from(swagger_ui: SwaggerUi) -> Self

Converts to this type from the input type.

impl From<SwaggerUi> for Vec<Route>

fn from(swagger_ui: SwaggerUi) -> Self

Converts to this type from the input type.

impl HttpServiceFactory for SwaggerUi

fn register(self, config: &mut AppService)