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.

Currently actix-web, rocket, axum frameworks supports SwaggerUi type.

Examples

Create new SwaggerUi with defaults.

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

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

let swagger = SwaggerUi::new("/swagger-ui/{_:.*}")
    .url("/api-doc/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-doc/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-doc/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-doc/openapi.json", true), ApiDoc::openapi()),
         (Url::new("api doc 2", "/api-doc/openapi2.json"), ApiDoc2::openapi())
    ]
);

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-doc/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-doc/openapi.json", ApiDoc::openapi())
    .config(Config::default().try_it_out_enabled(true).filter(true));