Struct utoipa_swagger_ui::Config

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

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, the Config can be also be 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

impl<'a> Config<'a>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for Config<'_>

fn default() -> Self

Returns the “default value” for a type.

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

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

Converts to this type from the input type.

impl From<String> for Config<'_>

fn from(s: String) -> Self

Converts to this type from the input type.

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

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

where __S: Serializer,

Serialize this value into the given Serde serializer.