Struct utoipa_swagger_ui::Config

source ·
#[non_exhaustive]
pub struct Config<'a> { /* private fields */ }
Expand description

Object used to alter Swagger UI settings.

Config struct provides Swagger UI configuration for settings which could be altered with docker variables.

§Examples

In simple case create config directly from url that points to the api doc json.

let config = Config::from("/api-doc.json");

If there is multiple api docs to serve config can be also directly created with Config::new

let config = Config::new(["/api-docs/openapi1.json", "/api-docs/openapi2.json"]);

Or same as above but more verbose syntax.

let config = Config::new([
    Url::new("api1", "/api-docs/openapi1.json"),
    Url::new("api2", "/api-docs/openapi2.json")
]);

With oauth config.

let config = Config::with_oauth_config(
    ["/api-docs/openapi1.json", "/api-docs/openapi2.json"],
    oauth::Config::new(),
);

Implementations§

source§

impl<'a> Config<'a>

source

pub fn new<I: IntoIterator<Item = U>, U: Into<Url<'a>>>(urls: I) -> Self

Constructs a new Config from Iterator of Urls.

Urls provided to the Config will only change the urls Swagger UI is going to use to fetch the API document. This does not change the URL that is defined with SwaggerUi::url or SwaggerUi::urls which defines the URL the API document is exposed from.

§Examples

Create new config with 2 api doc urls.

let config = Config::new(["/api-docs/openapi1.json", "/api-docs/openapi2.json"]);
source

pub fn with_oauth_config<I: IntoIterator<Item = U>, U: Into<Url<'a>>>( urls: I, oauth_config: Config, ) -> Self

Constructs a new Config from Iterator of Urls.

§Examples

Create new config with oauth config.

let config = Config::with_oauth_config(
    ["/api-docs/openapi1.json", "/api-docs/openapi2.json"],
    oauth::Config::new(),
);
source

pub fn config_url<S: Into<String>>(self, config_url: S) -> Self

Add url to fetch external configuration from.

§Examples

Set external config url.

let config = Config::new(["/api-docs/openapi.json"])
    .config_url("http://url.to.external.config");
source

pub fn dom_id<S: Into<String>>(self, dom_id: S) -> Self

Add id of the DOM element where Swagger UI will put it’s user interface.

The default value is #swagger-ui.

§Examples

Set custom dom id where the Swagger UI will place it’s content.

let config = Config::new(["/api-docs/openapi.json"]).dom_id("#my-id");
source

pub fn query_config_enabled(self, query_config_enabled: bool) -> Self

Set query_config_enabled to allow overriding configuration parameters via url query parameters.

Default value is false.

§Examples

Enable query config.

let config = Config::new(["/api-docs/openapi.json"])
    .query_config_enabled(true);
source

pub fn deep_linking(self, deep_linking: bool) -> Self

Set deep_linking to allow deep linking tags and operations.

Deep linking will automatically scroll to and expand operation when Swagger UI is given corresponding url fragment. See more at deep linking docs.

Deep linking is enabled by default.

§Examples

Disable the deep linking.

let config = Config::new(["/api-docs/openapi.json"])
    .deep_linking(false);
source

pub fn display_operation_id(self, display_operation_id: bool) -> Self

Set display_operation_id to true to show operation id in the operations list.

Default value is false.

§Examples

Allow operation id to be shown.

let config = Config::new(["/api-docs/openapi.json"])
    .display_operation_id(true);
source

pub fn use_base_layout(self) -> Self

Set ‘layout’ to ‘BaseLayout’ to only use the base swagger layout without a search header.

Default value is ‘StandaloneLayout’.

§Examples

Configure Swagger to use Base Layout instead of Standalone

let config = Config::new(["/api-docs/openapi.json"])
    .use_base_layout();
source

pub fn default_models_expand_depth( self, default_models_expand_depth: isize, ) -> Self

Add default models expansion depth.

Setting this to -1 will completely hide the models.

§Examples

Hide all the models.

let config = Config::new(["/api-docs/openapi.json"])
    .default_models_expand_depth(-1);
source

pub fn default_model_expand_depth( self, default_model_expand_depth: isize, ) -> Self

Add default model expansion depth for model on the example section.

§Examples
let config = Config::new(["/api-docs/openapi.json"])
    .default_model_expand_depth(1);
source

pub fn default_model_rendering<S: Into<String>>( self, default_model_rendering: S, ) -> Self

Add default_model_rendering to set how models is show when API is first rendered.

The user can always switch the rendering for given model by clicking the Model and Example Value links.

  • example Makes example rendered first by default.
  • model Makes model rendered first by default.
§Examples
let config = Config::new(["/api-docs/openapi.json"])
    .default_model_rendering(r#"["example"*, "model"]"#);
source

pub fn display_request_duration(self, display_request_duration: bool) -> Self

Set to true to show request duration of ‘Try it out’ requests (in milliseconds).

Default value is false.

§Examples

Enable request duration of the ‘Try it out’ requests.

let config = Config::new(["/api-docs/openapi.json"])
    .display_request_duration(true);
source

pub fn doc_expansion<S: Into<String>>(self, doc_expansion: S) -> Self

Add doc_expansion to control default expansion for operations and tags.

  • list Will expand only tags.
  • full Will expand tags and operations.
  • none Will expand nothing.
§Examples
let config = Config::new(["/api-docs/openapi.json"])
    .doc_expansion(r#"["list"*, "full", "none"]"#);
source

pub fn filter(self, filter: bool) -> Self

Add filter to allow filtering of tagged operations.

When enabled top bar will show and edit box that can be used to filter visible tagged operations. Filter behaves case sensitive manner and matches anywhere inside the tag.

Default value is false.

§Examples

Enable filtering.

let config = Config::new(["/api-docs/openapi.json"])
    .filter(true);
source

pub fn max_displayed_tags(self, max_displayed_tags: usize) -> Self

Add max_displayed_tags to restrict shown tagged operations.

By default all operations are shown.

§Examples

Display only 4 operations.

let config = Config::new(["/api-docs/openapi.json"])
    .max_displayed_tags(4);
source

pub fn show_extensions(self, show_extensions: bool) -> Self

Set show_extensions to adjust whether vendor extension (x-) fields and values are shown for operations, parameters, responses and schemas.

§Example

Show vendor extensions.

let config = Config::new(["/api-docs/openapi.json"])
    .show_extensions(true);
source

pub fn show_common_extensions(self, show_common_extensions: bool) -> Self

Add show_common_extensions to define whether common extension (pattern, maxLength, minLength, maximum, minimum) fields and values are shown for parameters.

§Examples

Show common extensions.

let config = Config::new(["/api-docs/openapi.json"])
    .show_common_extensions(true);
source

pub fn try_it_out_enabled(self, try_it_out_enabled: bool) -> Self

Add try_it_out_enabled to enable ‘Try it out’ section by default.

Default value is false.

§Examples

Enable ‘Try it out’ section by default.

let config = Config::new(["/api-docs/openapi.json"])
    .try_it_out_enabled(true);
source

pub fn request_snippets_enabled(self, request_snippets_enabled: bool) -> Self

Set request_snippets_enabled to enable request snippets section.

If disabled legacy curl snipped will be used.

Default value is false.

§Examples

Enable request snippets section.

let config = Config::new(["/api-docs/openapi.json"])
    .request_snippets_enabled(true);
source

pub fn oauth2_redirect_url<S: Into<String>>( self, oauth2_redirect_url: S, ) -> Self

Add oauth redirect url.

§Examples

Add oauth redirect url.

let config = Config::new(["/api-docs/openapi.json"])
    .oauth2_redirect_url("http://my.oauth2.redirect.url");
source

pub fn show_mutated_request(self, show_mutated_request: bool) -> Self

Add show_mutated_request to use request returned from requestInterceptor to produce curl command in the UI. If set to false the request before requestInterceptor was applied will be used.

§Examples

Use request after requestInterceptor to produce the curl command.

let config = Config::new(["/api-docs/openapi.json"])
    .show_mutated_request(true);
source

pub fn supported_submit_methods<I: IntoIterator<Item = S>, S: Into<String>>( self, supported_submit_methods: I, ) -> Self

Add supported http methods for ‘Try it out’ operation.

‘Try it out’ will be enabled based on the given list of http methods when the operation’s http method is included within the list. By giving an empty list will disable ‘Try it out’ from all operations but it will not filter operations from the UI.

By default all http operations are enabled.

§Examples

Set allowed http methods explicitly.

let config = Config::new(["/api-docs/openapi.json"])
    .supported_submit_methods(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);

Allow ‘Try it out’ for only GET operations.

let config = Config::new(["/api-docs/openapi.json"])
    .supported_submit_methods(["get"]);
source

pub fn validator_url<S: Into<String>>(self, validator_url: S) -> Self

Add validator url which is used to validate the Swagger spec.

This can also be set to use locally deployed validator for example see Validator Badge for more details.

By default swagger.io’s online validator (https://validator.swagger.io/validator) will be used. Setting this to none will disable the validator.

§Examples

Disable the validator.

let config = Config::new(["/api-docs/openapi.json"])
    .validator_url("none");
source

pub fn with_credentials(self, with_credentials: bool) -> Self

Set with_credentials to enable passing credentials to CORS requests send by browser as defined fetch standards.

Note! that Swagger UI cannot currently set cookies cross-domain (see swagger-js#1163) - as a result, you will have to rely on browser-supplied cookies (which this setting enables sending) that Swagger UI cannot control.

§Examples

Enable passing credentials to CORS requests.

let config = Config::new(["/api-docs/openapi.json"])
    .with_credentials(true);
source

pub fn persist_authorization(self, persist_authorization: bool) -> Self

Set to true to enable authorizations to be persisted throughout browser refresh and close.

Default value is false.

§Examples

Persists authorization throughout browser close and refresh.

let config = Config::new(["/api-docs/openapi.json"])
    .persist_authorization(true);

Trait Implementations§

source§

impl<'a> Clone for Config<'a>

source§

fn clone(&self) -> Config<'a>

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 Default for Config<'_>

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl<'a> From<&'a str> for Config<'a>

source§

fn from(s: &'a str) -> Self

Converts to this type from the input type.
source§

impl From<String> for Config<'_>

source§

fn from(s: String) -> Self

Converts to this type from the input type.
source§

impl<'a> Serialize for Config<'a>

source§

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer,

Serialize this value into the given Serde serializer. Read more

Auto Trait Implementations§

§

impl<'a> Freeze for Config<'a>

§

impl<'a> RefUnwindSafe for Config<'a>

§

impl<'a> Send for Config<'a>

§

impl<'a> Sync for Config<'a>

§

impl<'a> Unpin for Config<'a>

§

impl<'a> UnwindSafe for Config<'a>

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