Struct utoipa_swagger_ui::SwaggerUi

source ·

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

Expand description

Entry point for serving Swagger UI and api docs in application. It uses 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§

source §

impl SwaggerUi

source

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/{_:.*}");

source

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());

source

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())
    ]
);

source

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);

source

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)
     ]);

source

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)
    );

source

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));