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

Trait Implementations§

source§

impl Clone for SwaggerUi

source§

fn clone(&self) -> SwaggerUi

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl HttpServiceFactory for SwaggerUi

source§

fn register(self, config: &mut AppService)

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more