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>
impl<'a> Config<'a>
sourcepub fn new<I: IntoIterator<Item = U>, U: Into<Url<'a>>>(urls: I) -> Self
pub fn new<I: IntoIterator<Item = U>, U: Into<Url<'a>>>(urls: I) -> Self
Constructs a new Config
from Iterator
of Url
s.
Url
s 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"]);
sourcepub fn with_oauth_config<I: IntoIterator<Item = U>, U: Into<Url<'a>>>(
urls: I,
oauth_config: Config
) -> Self
pub fn with_oauth_config<I: IntoIterator<Item = U>, U: Into<Url<'a>>>( urls: I, oauth_config: Config ) -> Self
sourcepub fn config_url<S: Into<String>>(self, config_url: S) -> Self
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");
sourcepub fn dom_id<S: Into<String>>(self, dom_id: S) -> Self
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");
sourcepub fn query_config_enabled(self, query_config_enabled: bool) -> Self
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);
sourcepub fn deep_linking(self, deep_linking: bool) -> Self
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);
sourcepub fn display_operation_id(self, display_operation_id: bool) -> Self
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);
sourcepub fn use_base_layout(self) -> Self
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();
sourcepub fn default_models_expand_depth(
self,
default_models_expand_depth: isize
) -> Self
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);
sourcepub fn default_model_expand_depth(
self,
default_model_expand_depth: isize
) -> Self
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);
sourcepub fn default_model_rendering<S: Into<String>>(
self,
default_model_rendering: S
) -> Self
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"]"#);
sourcepub fn display_request_duration(self, display_request_duration: bool) -> Self
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);
sourcepub fn doc_expansion<S: Into<String>>(self, doc_expansion: S) -> Self
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"]"#);
sourcepub fn filter(self, filter: bool) -> Self
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);
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);
sourcepub fn show_extensions(self, show_extensions: bool) -> Self
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);
sourcepub fn show_common_extensions(self, show_common_extensions: bool) -> Self
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);
sourcepub fn try_it_out_enabled(self, try_it_out_enabled: bool) -> Self
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);
sourcepub fn request_snippets_enabled(self, request_snippets_enabled: bool) -> Self
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);
sourcepub fn oauth2_redirect_url<S: Into<String>>(
self,
oauth2_redirect_url: S
) -> Self
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");
sourcepub fn show_mutated_request(self, show_mutated_request: bool) -> Self
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);
sourcepub fn supported_submit_methods<I: IntoIterator<Item = S>, S: Into<String>>(
self,
supported_submit_methods: I
) -> Self
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"]);
sourcepub fn validator_url<S: Into<String>>(self, validator_url: S) -> Self
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");
sourcepub fn with_credentials(self, with_credentials: bool) -> Self
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);
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);