Utoipa

https://docs.rs/utoipa
Admin
Utoipa provides autogenerated OpenAPI documentation for Rust REST APIs, simplifying API...
Tokens:652,821
Snippets:6,325
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example::new

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/example.rs.html

Constructs a new empty Example instance, equivalent to Example::default().

```APIDOC
## Example::new

### Description
Constructs a new empty Example instance. This is effectively the same as calling Example::default().

### Method
new

### Signature
pub fn new() -> Self

### Parameters
None

### Returns
A new Example instance with default values.
```

--------------------------------

### Construct a new Example via ExampleBuilder

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/example.rs.html

Shows how to use the ExampleBuilder to create an Example with a summary and a JSON value. The example uses serde_json::json! to set the value.

```rust
# use utoipa::openapi::example::ExampleBuilder;
let example = ExampleBuilder::new()
    .summary("Example string response")
    .value(Some(serde_json::json!("Example value")))
    .build();
```

--------------------------------

### Multiple examples on a single response in `#[utoipa::path]`

Source: https://docs.rs/utoipa/latest/utoipa/attr.path.html?search=

Shows how to define multiple examples on a single response using the `examples` keyword, each with a summary, optional description, and value.

```rust
#[utoipa::path(
    get,
    path = "/user",
    responses(
        (status = 200, body = User,
            examples(
                ("Demo" = (summary = "This is summary", description = "Long description",
                            value = json!(User{name: "Demo".to_string()}))),
                ("John" = (summary = "Another user", value = json!({"name": "John"})))
             )
        )
    )
)]
fn get_user() -> User {
  User {name: "John".to_string()}
}
```

--------------------------------

### Complete responses(...) with body and example

Source: https://docs.rs/utoipa/latest/utoipa/attr.path.html?search=

More complete `responses(...)` example that adds `body`, `content_type`, `headers(...)`, and `example` fields to a response tuple.

```rust
responses(
    (status = 200, description = "Success response", body = Pet, content_type = "application/json",
        headers(...),
        example = json!({"id": 1, "name": "bob the cat"})
    )
)
```

--------------------------------

### ObjectBuilder with examples

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/schema.rs.html

Adds examples to the object schema using the examples method.

```rust
let json_value = ObjectBuilder::new()
    .examples([Some(json!({"age": 20, "name": "bob the cat"}))])
    .build();
assert_json_snapshot!(json_value, @r#"
{
  "type": "object",
  "examples": [
    {
      "age": 20,
      "name": "bob the cat"
    }
  ]
}
"#);
```

--------------------------------

### Response examples(...) syntax example

Source: https://docs.rs/utoipa/latest/utoipa/attr.path.html?search=

Defines a single response example named "John" with a summary and a JSON value. The value must be parseable by serde_json::json!.

```rust
("John" = (summary = "This is John", value = json!({"name": "John"})))
```

--------------------------------

### Define a response example

Source: https://docs.rs/utoipa/latest/utoipa/attr.path.html

An example of how to define a named response example using the examples attribute syntax.

```rust
 ("John" = (summary = "This is John", value = json!({"name": "John"})))
```

--------------------------------

### ExampleBuilder and Example

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/example.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Documentation for the ExampleBuilder and Example types in the utoipa openapi module, including builder methods for constructing OpenAPI Example objects.

```APIDOC
## ExampleBuilder::new()

### Description
Constructs a new `ExampleBuilder` instance for building an OpenAPI `Example` object.

### Method
`ExampleBuilder::new()`

### Parameters
None

### Returns
A new `ExampleBuilder` instance.

### Example
```rust
let example = ExampleBuilder::new()
    .summary("Example string response")
    .value(Some(serde_json::json!("Example value")))
    .build();
```
```

```APIDOC
## ExampleBuilder::summary(S)

### Description
Adds or changes a short description for the `Example`. Setting this to an empty `String` will make it not render in the generated OpenAPI document.

### Method
`ExampleBuilder::summary<S: Into<String>>(mut self, summary: S) -> Self`

### Parameters
- **summary** (`S: Into<String>`) - Required - Short description for the example.

### Returns
The builder instance with the summary set.
```

```APIDOC
## ExampleBuilder::description(D)

### Description
Adds or changes a long description for the `Example`. Markdown syntax is supported for rich text representation. Setting this to an empty `String` will make it not render in the generated OpenAPI document.

### Method
`ExampleBuilder::description<D: Into<String>>(mut self, description: D) -> Self`

### Parameters
- **description** (`D: Into<String>`) - Required - Long description for the example.

### Returns
The builder instance with the description set.
```

```APIDOC
## ExampleBuilder::value(Option<serde_json::Value>)

### Description
Adds or changes an embedded literal example value. `Example::value` and `Example::external_value` are mutually exclusive.

### Method
`ExampleBuilder::value(mut self, value: Option<serde_json::Value>) -> Self`

### Parameters
- **value** (`Option<serde_json::Value>`) - Required - Embedded literal example value.

### Returns
The builder instance with the value set.
```

```APIDOC
## ExampleBuilder::external_value(E)

### Description
Adds or changes a URI that points to a literal example value. `Example::external_value` provides the capability to reference an example that cannot be easily included in JSON or YAML. `Example::value` and `Example::external_value` are mutually exclusive. Setting this to an empty `String` will make the field not render in the generated OpenAPI document.

### Method
`ExampleBuilder::external_value<E: Into<String>>(mut self, external_value: E) -> Self`

### Parameters
- **external_value** (`E: Into<String>`) - Required - URI pointing to a literal example value.

### Returns
The builder instance with the external value set.
```

```APIDOC
## Example::new()

### Description
Constructs a new empty `Example`. This is effectively the same as calling `Example::default`.

### Method
`Example::new() -> Self`

### Parameters
None

### Returns
A new empty `Example` instance.
```

--------------------------------

### Example struct and builder implementation

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/example.rs.html?search=std%3A%3Avec

Full source of example.rs defining the Example struct, ExampleBuilder, and their methods.

```rust
//! Implements [OpenAPI Example Object][example] can be used to define examples for [`Response`][response]s and
//! [`RequestBody`][request_body]s.
//!
//! [example]: https://spec.openapis.org/oas/latest.html#example-object
//! [response]: response/struct.Response.html
//! [request_body]: request_body/struct.RequestBody.html
use serde::{Deserialize, Serialize};

use super::{builder, set_value, RefOr};

builder! {
    /// # Examples
    ///
    /// _**Construct a new [`Example`] via builder**_
    /// ```rust
    /// # use utoipa::openapi::example::ExampleBuilder;
    /// let example = ExampleBuilder::new()
    ///     .summary("Example string response")
    ///     .value(Some(serde_json::json!("Example value")))
    ///     .build();
    /// ```
    ExampleBuilder;

    /// Implements [OpenAPI Example Object][example].
    ///
    /// Example is used on path operations to describe possible response bodies.
    ///
    /// [example]: https://spec.openapis.org/oas/latest.html#example-object
    #[non_exhaustive]
    #[derive(Serialize, Deserialize, Default, Clone, PartialEq, Eq)]
    #[cfg_attr(feature = "debug", derive(Debug))]
    #[serde(rename_all = "camelCase")]
    pub struct Example {
        /// Short description for the [`Example`].
        #[serde(skip_serializing_if = "String::is_empty", default)]
        pub summary: String,

        /// Long description for the [`Example`]. Value supports markdown syntax for rich text
        /// representation.
        #[serde(skip_serializing_if = "String::is_empty", default)]
        pub description: String,

        /// Embedded literal example value. [`Example::value`] and [`Example::external_value`] are
        /// mutually exclusive.
        #[serde(skip_serializing_if = "Option::is_none")]
        pub value: Option<serde_json::Value>,

        /// An URI that points to a literal example value. [`Example::external_value`] provides the
        /// capability to references an example that cannot be easily included in JSON or YAML.
        /// [`Example::value`] and [`Example::external_value`] are mutually exclusive.
        #[serde(skip_serializing_if = "String::is_empty", default)]
        pub external_value: String,
    }
}

impl Example {
    /// Construct a new empty [`Example`]. This is effectively same as calling
    /// [`Example::default`].
    pub fn new() -> Self {
        Self::default()
    }
}

impl ExampleBuilder {
    /// Add or change a short description for the [`Example`]. Setting this to empty `String`
    /// will make it not render in the generated OpenAPI document.
    pub fn summary<S: Into<String>>(mut self, summary: S) -> Self {
        set_value!(self summary summary.into())
    }

    /// Add or change a long description for the [`Example`]. Markdown syntax is supported for rich
    /// text representation.
    ///
    /// Setting this to empty `String` will make it not render in the generated
    /// OpenAPI document.
    pub fn description<D: Into<String>>(mut self, description: D) -> Self {
        set_value!(self description description.into())
    }

    /// Add or change embedded literal example value. [`Example::value`] and [`Example::external_value`]
    /// are mutually exclusive.
    pub fn value(mut self, value: Option<serde_json::Value>) -> Self {
        set_value!(self value value)
    }

    /// Add or change an URI that points to a literal example value. [`Example::external_value`]
    /// provides the capability to references an example that cannot be easily included
    /// in JSON or YAML. [`Example::value`] and [`Example::external_value`] are mutually exclusive.
    ///
    /// Setting this to an empty String will make the field not to render in the generated OpenAPI
    /// document.
    pub fn external_value<E: Into<String>>(mut self, external_value: E) -> Self {
        set_value!(self external_value external_value.into())
    }
}

impl From<ExampleBuilder> for RefOr<Example> {
    fn from(example_builder: ExampleBuilder) -> Self {
        Self::T(example_builder.build())
    }
}
```

--------------------------------

### ContentBuilder::example

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/content.rs.html?search=std%3A%3Avec

Adds an example value to the Content being built. The example is optional and can be any JSON value.

```APIDOC
## ContentBuilder::example

### Description
Adds an example of the schema to the Content being built.

### Method
ContentBuilder::example

### Parameters
- **example** (Option<Value>) - Optional - The example value to add.

### Returns
- **ContentBuilder** - The builder with the example set.

### Example
```rust
let builder = ContentBuilder::new().example(Some(json!({ "name": "John" })));
```
```

--------------------------------

### Schema::example

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/schema.rs.html

Sets an example shown in UI for richer documentation. Deprecated since 3.0.x, prefer examples.

```APIDOC
## Schema::example

### Description
Sets an example shown in UI for richer documentation. Deprecated since 3.0.x, prefer examples.

### Method
`pub fn example(mut self, example: Option<Value>) -> Self`

### Parameters
- **example** (Option<Value>) - Optional - The example value.

### Returns
Returns the modified Schema instance for chaining.
```

--------------------------------

### bright() example

Source: https://docs.rs/utoipa-swagger-ui/latest/utoipa_swagger_ui/struct.BasicAuth.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Sets the quirk to Bright. Example prints the value with the bright quirk applied.

```rust
println!("{}", value.bright());
```

--------------------------------

### Object::example

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/schema.rs.html?search=u32+-%3E+bool

Sets an example value for richer documentation. Deprecated since 3.0.x, prefer examples instead.

```APIDOC
## Method

`pub fn example(mut self, example: Option<Value>) -> Self`

### Description

Add or change example shown in UI of the value for richer documentation. Deprecated since 3.0.x. Prefer Object::examples instead.

### Parameters

- `example` (Option<Value>) - Required - The example value.
```

--------------------------------

### Example Struct

Source: https://docs.rs/utoipa/latest/utoipa/openapi/example/struct.Example.html?search=

Documentation for the Example struct in the utoipa::openapi::example module, including its fields and constructors.

```APIDOC
## Struct Example

### Description
Implements OpenAPI Example Object. Example is used on path operations to describe possible response bodies.

### Fields
- **summary** (String) - Short description for the `Example`.
- **description** (String) - Long description for the `Example`. Value supports markdown syntax for rich text representation.
- **value** (Option<Value>) - Embedded literal example value. `Example::value` and `Example::external_value` are mutually exclusive.
- **external_value** (String) - An URI that points to a literal example value. `Example::external_value` provides the capability to references an example that cannot be easily included in JSON or YAML. `Example::value` and `Example::external_value` are mutually exclusive.

### Methods

#### builder() -> ExampleBuilder
Construct a new ExampleBuilder. This is effectively same as calling `ExampleBuilder::new`.

#### new() -> Self
Construct a new empty `Example`. This is effectively same as calling `Example::default`.
```

--------------------------------

### Create new server with alternative server

Source: https://docs.rs/utoipa/latest/utoipa/openapi/server/struct.Server.html?search=

Demonstrates how to initialize a Server instance using a full HTTP URL.

```rust
 Server::new("https://alternative.pet-api.test/api/v1");
```

--------------------------------

### Panic example: duplicate GET paths

Source: https://docs.rs/utoipa-axum/latest/utoipa_axum/macro.routes.html?search=u32+-%3E+bool

Shows that registering two handlers with the same HTTP method (GET) via `routes!` causes a runtime panic from axum.

```rust
 #[utoipa::path(get, path = "/search")]
 async fn search_user() {}

 #[utoipa::path(get, path = "")]
 async fn get_user() {}

 let _: UtoipaMethodRouter = routes!(get_user, search_user);
```

--------------------------------

### Crate utoipa_actix_web

Source: https://docs.rs/utoipa-actix-web/latest/utoipa_actix_web/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Overview of the utoipa_actix_web crate, including installation, usage example, and key components.

```APIDOC
## [Crate] utoipa_actix_web

### Description
This crate provides bindings for automatically collecting `paths` and `schemas` from Actix Web `App`, `Scope`, and `ServiceConfig` to generate OpenAPI specifications. It reduces duplication and supports scopes without manually declaring `paths` and `schemas` in the `#[openapi(...)]` attribute.

### Usage
Add the dependency to `Cargo.toml`:
```toml
[dependencies]
utoipa-actix-web = "0.1"
```

### Example
```rust
use actix_web::web::Json;
use actix_web::{get, App};
use utoipa_actix_web::{scope, AppExt};

#[derive(utoipa::ToSchema, serde::Serialize)]
struct User {
    id: i32,
}

#[utoipa::path(responses((status = OK, body = User)))]
#[get("/user")]
async fn get_user() -> Json<User> {
    Json(User { id: 1 })
}

let (_, mut api) = App::new()
    .into_utoipa_app()
    .service(scope::scope("/api/v1").service(get_user))
    .split_for_parts();
```

### Re-exports
- `pub use scope::scope;`

### Modules
- `scope`: Implement `utoipa` extended `Scope` for `actix_web::Scope`.
- `service_config`: Implement `utoipa` extended `ServiceConfig` for `actix_web::web::ServiceConfig`.

### Structs
- `UtoipaApp`: Wrapper type for `actix_web::App` and `utoipa::openapi::OpenApi`.

### Traits
- `AppExt`: Extends `actix_web::App` with `utoipa` related functionality.
- `OpenApiFactory`: Trait used to unify OpenAPI items collection from types implementing this trait.
```

--------------------------------

### Create new server with url path

Source: https://docs.rs/utoipa/latest/utoipa/openapi/server/struct.Server.html?search=

Demonstrates how to initialize a Server instance using a context path.

```rust
 Server::new("/api/v1");
```

--------------------------------

### Runtime panic example for duplicate HTTP methods in routes! macro

Source: https://docs.rs/utoipa-axum/latest/src/utoipa_axum/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This example demonstrates that registering two handlers with the same HTTP method (GET) via the routes! macro will cause a runtime panic from axum, as only one HTTP method can be registered per call.

```rust
# use utoipa_axum::{routes, router::UtoipaMethodRouter};
# use utoipa::path;
 #[utoipa::path(get, path = "/search")]
 async fn search_user() {}

 #[utoipa::path(get, path = "")]
 async fn get_user() {}

 let _: UtoipaMethodRouter = routes!(get_user, search_user);
```

--------------------------------

### get_disjoint_mut with duplicate keys panic

Source: https://docs.rs/utoipa/latest/utoipa/openapi/extensions/struct.Extensions.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows that calling get_disjoint_mut with duplicate keys causes a panic. The example attempts to get mutable references for the same key twice.

```rust
// Duplicate keys panic!
let got = libraries.get_disjoint_mut([
    "Athenæum",
    "Athenæum",
]);
```

--------------------------------

### Construct an Example via ExampleBuilder

Source: https://docs.rs/utoipa/latest/utoipa/openapi/example/struct.ExampleBuilder.html

Shows how to create an `Example` using the builder pattern with `summary` and `value` methods. The `value` method takes an `Option<Value>` and is mutually exclusive with `external_value`.

```rust
let example = ExampleBuilder::new()
    .summary("Example string response")
    .value(Some(serde_json::json!("Example value")))
    .build();
```

--------------------------------

### Get path item by relative path

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/path.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns a reference to the `PathItem` for the given relative path, or `None` if not found. The example uses `Paths::new()` and calls `get_path_item` with a path string.

```rust
use utoipa::openapi::path::{Paths, HttpMethod};
let paths = Paths::new();
let path_item = paths.get_path_item("/api/v1/user");
```

--------------------------------

### Module: pets with get_pet route

Source: https://docs.rs/utoipa-axum/latest/src/utoipa_axum/lib.rs.html

Defines a module named pets containing a route handler get_pet with a GET path '/'. This is a minimal example of using the utoipa::path macro to define a route.

```rust
mod pets {

    #[utoipa::path(get, path = "/")]
    pub async fn get_pet() {}
}
```

--------------------------------

### Get path operation by path and HTTP method

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/path.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns a reference to the `Operation` for the given path and HTTP method, or `None` if not found. The example uses `Paths::new()` and calls `get_path_operation` with a path and `HttpMethod::Get`.

```rust
use utoipa::openapi::path::{Paths, HttpMethod};
let paths = Paths::new();
let operation = paths.get_path_operation("/api/v1/user", HttpMethod::Get);
```

--------------------------------

### ExampleBuilder::build

Source: https://docs.rs/utoipa/latest/utoipa/openapi/example/struct.ExampleBuilder.html

Constructs a new Example taking all field values from this builder.

```APIDOC
## ExampleBuilder::build

### Description
Constructs a new `Example` taking all fields values from this object.

### Method
build

### Signature
pub fn build(self) -> Example

### Parameters
None

### Returns
Example - The constructed Example.
```

--------------------------------

### actix_extras with Params

Source: https://docs.rs/utoipa/latest/utoipa/attr.path.html?search=

Example of using actix_extras to parse path and operation information from actix-web macros. The path, operation, and parameter types are inferred from the #[get] attribute and the handler arguments, so only responses and optional params need to be specified.

```rust
use actix_web::{get, web, HttpResponse, Responder};
use serde_json::json;

/// Get Pet by id
#[utoipa::path(
    responses(
        (status = 200, description = "Pet found from database")
    ),
    params(
        ("id", description = "Pet id"),
    )
)]
#[get("/pet/{id}")]
async fn get_pet_by_id(id: web::Path<i32>) -> impl Responder {
    HttpResponse::Ok().json(json!({ "pet": format!("{:?}", &id.into_inner()) }))
}

```

--------------------------------

### Schema::examples

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/schema.rs.html

Sets multiple examples shown in UI for richer documentation.

```APIDOC
## Schema::examples

### Description
Sets multiple examples shown in UI for richer documentation.

### Method
`pub fn examples<I: IntoIterator<Item = V>, V: Into<Value>>(mut self, examples: I) -> Self`

### Parameters
- **examples** (I) - Required - The examples to set.

### Returns
Returns the modified Schema instance for chaining.
```

--------------------------------

### Implement Path trait using #[utoipa::path] macro

Source: https://docs.rs/utoipa/latest/src/utoipa/lib.rs.html?search=std%3A%3Avec

Demonstrates using the #[utoipa::path] attribute macro to implement the Path trait for an async function get_pet_by_id. The example defines a Pet struct, sets up a GET endpoint at /pets/{id} with responses and a path parameter.

```rust
/// # #[derive(utoipa::ToSchema)]
/// # struct Pet {
/// #   id: u64,
/// #   name: String,
/// # }
/// #
/// #
/// /// Get pet by id
/// ///
/// /// Get pet from database by pet database id
/// #[utoipa::path(
///     get,
///     path = "/pets/{id}",
///     responses(
///         (status = 200, description = "Pet found successfully", body = Pet),
///         (status = 404, description = "Pet was not found")
///     ),
///     params(
///         ("id" = u64, Path, description = "Pet database id to get Pet for"),
///     )
/// )]
/// async fn get_pet_by_id(pet_id: u64) -> Pet {
///     Pet {
///         id: pet_id,
///         name: "lightning".to_string(),
///     }
/// }
```

--------------------------------

### Object::examples

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/schema.rs.html?search=u32+-%3E+bool

Sets multiple example values for richer documentation.

```APIDOC
## Method

`pub fn examples<I: IntoIterator<Item = V>, V: Into<Value>>(mut self, examples: I) -> Self`

### Description

Add or change examples shown in UI of the value for richer documentation.

### Parameters

- `examples` (I) - Required - The examples to set.
```

--------------------------------

### Create new scoped service with utoipa_actix_web::scope

Source: https://docs.rs/utoipa-actix-web/latest/src/utoipa_actix_web/scope.rs.html?search=std%3A%3Avec

Example from the `scope` function documentation showing how to create a new scoped service using `scope::scope("/api/v1/inner")` and configure it with a handler. The handler is annotated with `#[utoipa::path()]` and `#[get("/handler")]`.

```rust
# use actix_web::{get, App};
# use utoipa_actix_web::{AppExt, scope};
#
 #[utoipa::path()]
 #[get("/handler")]
 pub async fn handler() -> &'static str {
     "OK"
 }
let _ = App::new()
    .into_utoipa_app()
    .service(scope::scope("/api/v1/inner").configure(|cfg| {
        cfg.service(handler);
    }));
```

--------------------------------

### Construct Info using Info::new

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/info.rs.html

Demonstrates the simplest way to create a new Info object by providing a title and version string.

```rust
# use utoipa::openapi::Info;
let info = Info::new("Pet api", "1.1.0");
```

--------------------------------

### Example::builder()

Source: https://docs.rs/utoipa/latest/utoipa/openapi/example/struct.Example.html

Constructs a new ExampleBuilder. This is effectively the same as calling ExampleBuilder::new.

```APIDOC
## Example::builder()

### Description
Constructs a new ExampleBuilder. This is effectively the same as calling ExampleBuilder::new.

### Method
builder

### Signature
pub fn builder() -> ExampleBuilder

### Returns
ExampleBuilder - A new ExampleBuilder instance.
```

--------------------------------

### Create a scoped service with auto schema collection

Source: https://docs.rs/utoipa-actix-web/latest/utoipa_actix_web/scope/fn.scope.html

Creates a scoped service at `/api/v1/inner` that automatically collects schemas and paths from the handler registration. The example uses `#[utoipa::path]` and `#[get]` attributes to define a handler, then registers it in a `Scope` via `scope::scope` and `configure`. Requires the `actix_web` and `utoipa_actix_web` crates.

```rust
pub fn scope<I: Into<Scope<T>>, T: ServiceFactory<ServiceRequest, Config = (), Error = Error, InitError = ()>>(
    scope: I,
) -> Scope<T>
```

```rust
#[utoipa::path()]
#[get("/handler")]
pub async fn handler() -> &'static str {
    "OK"
}
let _ = App::new()
    .into_utoipa_app()
    .service(scope::scope("/api/v1/inner").configure(|cfg| {
        cfg.service(handler);
    }));
```

--------------------------------

### AnyOfBuilder::examples

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/schema.rs.html?search=u32+-%3E+bool

Adds or changes examples shown in UI of the value for richer documentation.

```APIDOC
## AnyOfBuilder::examples

### Description
Adds or changes examples shown in UI of the value for richer documentation.

### Method
`pub fn examples<I: IntoIterator<Item = V>, V: Into<Value>>(mut self, examples: I) -> Self`

### Parameters
- **examples** (I) - Required - An iterator of example values.

### Returns
`Self` - The builder instance for chaining.
```

--------------------------------

### ExampleBuilder::summary

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/example.rs.html

Sets the short description for the Example. If set to an empty string, it will not render in the generated OpenAPI document.

```APIDOC
## ExampleBuilder::summary

### Description
Add or change a short description for the Example. Setting this to an empty String will make it not render in the generated OpenAPI document.

### Method
summary

### Signature
pub fn summary<S: Into<String>>(mut self, summary: S) -> Self

### Parameters
- **summary** (S) - Required - The short description to set.

### Returns
The builder instance with the summary set.
```

--------------------------------

### default_model_rendering example

Source: https://docs.rs/utoipa-swagger-ui/latest/utoipa_swagger_ui/struct.Config.html

Sets the default model rendering to show example first. The user can switch between 'Model' and 'Example Value' links.

```rust
let config = Config::new(["/api-docs/openapi.json"])
    .default_model_rendering(r#"["example"*, "model"]"#);
```

--------------------------------

### AllOfBuilder::examples

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/schema.rs.html?search=u32+-%3E+bool

Adds or changes examples shown in UI of the value for richer documentation.

```APIDOC
## AllOfBuilder::examples

### Description
Adds or changes examples shown in UI of the value for richer documentation.

### Method
pub fn examples<I: IntoIterator<Item = V>, V: Into<Value>>(mut self, examples: I) -> Self

### Parameters
- **examples** (I) - Required - An iterator of values to set as examples.

### Returns
Self - The builder instance for chaining.

```

--------------------------------

### new

Source: https://docs.rs/utoipa-swagger-ui/latest/utoipa_swagger_ui/struct.BasicAuth.html?search=std%3A%3Avec

Constructor to create a new Painted instance.

```APIDOC
## `new`

### Description
Create a new `Painted` with a default `Style`.

### Method
`fn new(self) -> Painted<Self> where Self: Sized`

```

--------------------------------

### AnyOfBuilder::example

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/schema.rs.html?search=u32+-%3E+bool

Adds or changes the example shown in UI of the value for richer documentation. Deprecated since 3.0.x, prefer examples instead.

```APIDOC
## AnyOfBuilder::example

### Description
Adds or changes the example shown in UI of the value for richer documentation. **Deprecated since 3.0.x. Prefer `AllOfBuilder::examples` instead** n
### Method
`pub fn example(mut self, example: Option<Value>) -> Self` n
### Parameters
- **example** (Option<Value>) - Required - The example value to set.

### Returns
`Self` - The builder instance for chaining.
```

--------------------------------

### ExampleBuilder::new()

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/example.rs.html?search=std%3A%3Avec

Constructs a new ExampleBuilder instance for building an Example object.

```APIDOC
## ExampleBuilder::new()

### Description
Constructs a new `ExampleBuilder` instance for building an `Example` object.

### Method
`ExampleBuilder::new()`

### Parameters
None

### Returns
A new `ExampleBuilder` instance.

### Example
```rust
let example = ExampleBuilder::new()
    .summary("Example string response")
    .value(Some(serde_json::json!("Example value")))
    .build();
```
```

--------------------------------

### Allow only GET operations with supported_submit_methods

Source: https://docs.rs/utoipa-swagger-ui/latest/src/utoipa_swagger_ui/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Allows 'Try it out' for only GET operations.

```rust
# use utoipa_swagger_ui::Config;
let config = Config::new(["/api-docs/openapi.json"])
    .supported_submit_methods(["get"]);
```

--------------------------------

### Create SwaggerUi with custom configuration

Source: https://docs.rs/utoipa-swagger-ui/latest/src/utoipa_swagger_ui/lib.rs.html?search=u32+-%3E+bool

Demonstrates how to initialize a new SwaggerUi instance with custom configuration options enabled.

```rust
# use utoipa_swagger_ui::{SwaggerUi, Config};
# use utoipa::OpenApi;
# #[derive(OpenApi)]
# #[openapi()]
# struct ApiDoc;
let swagger = SwaggerUi::new("/swagger-ui/{_:.*}")
    .url("/api-docs/openapi.json", ApiDoc::openapi())
    .config(Config::default().try_it_out_enabled(true).filter(true));
```

--------------------------------

### Derive Example

Source: https://docs.rs/utoipa/latest/utoipa/trait.ToSchema.html?search=u32+-%3E+bool

Example of using #[derive(ToSchema)] to implement the trait for a struct.

```APIDOC
## Derive Example

### Description
Example of using `#[derive(ToSchema)]` to implement the trait for a struct.

### Code
```rust
#[derive(ToSchema)]
#[schema(example = json!({"name": "bob the cat", "id": 1}))]
struct Pet {
    id: u64,
    name: String,
    age: Option<i32>,
}
```
```

--------------------------------

### Manual Implementation Example

Source: https://docs.rs/utoipa/latest/utoipa/trait.ToSchema.html?search=u32+-%3E+bool

Example of manually implementing the ToSchema and PartialSchema traits for a struct.

```APIDOC
## Manual Implementation Example

### Description
Example of manually implementing the `ToSchema` and `PartialSchema` traits for a struct.

### Code
```rust
impl utoipa::ToSchema for Pet {
    fn name() -> std::borrow::Cow<'static, str> {
        std::borrow::Cow::Borrowed("Pet")
    }
}
impl utoipa::PartialSchema for Pet {
    fn schema() -> utoipa::openapi::RefOr<utoipa::openapi::schema::Schema> {
        utoipa::openapi::ObjectBuilder::new()
            .property(
                "id",
                utoipa::openapi::ObjectBuilder::new()
                    .schema_type(utoipa::openapi::schema::Type::Integer)
                    .format(Some(utoipa::openapi::SchemaFormat::KnownFormat(
                        utoipa::openapi::KnownFormat::Int64,
                    ))),
            )
            .required("id")
            .property(
                "name",
                utoipa::openapi::ObjectBuilder::new()
                    .schema_type(utoipa::openapi::schema::Type::String),
            )
            .required("name")
            .property(
                "age",
                utoipa::openapi::ObjectBuilder::new()
                    .schema_type(utoipa::openapi::schema::Type::Integer)
                    .format(Some(utoipa::openapi::SchemaFormat::KnownFormat(
                        utoipa::openapi::KnownFormat::Int32,
                    ))),
            )
            .example(Some(serde_json::json!({
              "name":"bob the cat","id":1
            })))
            .into()
    }
}
```
```

--------------------------------

### Create OpenApi using OpenApiBuilder

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi.rs.html?search=std%3A%3Avec

Shows how to construct an `OpenApi` instance using the `OpenApiBuilder` with `Info`, `Paths`, and `Components`. This is the recommended way to build an OpenAPI document when you need to set multiple fields.

```rust
use utoipa::openapi::{Info, Paths, Components, OpenApiBuilder};
let openapi = OpenApiBuilder::new()
     .info(Info::new("My api", "1.0.0"))
     .paths(Paths::new())
     .components(Some(
         Components::new()
     ))
     .build();
```

--------------------------------

### Tuples format example in params(...)

Source: https://docs.rs/utoipa/latest/utoipa/attr.path.html?search=

Example of the tuples format inside `params(...)`. It shows `parameter_type`, `in`, `description`, `deprecated`, `style`, `allow_reserved`, `explode`, `example`, and type attributes such as `max_length` and `min_items`.

```rust
params(
    ("limit" = i32, Query),
    ("x-custom-header" = String, Header, description = "Custom header"),
    ("id" = String, Path, deprecated, description = "Pet database id"),
    ("name", Path, deprecated, description = "Pet name"),
    (
        "value" = inline(Option<[String]>),
        Query,
        description = "Value description",
        style = Form,
        allow_reserved,
        deprecated,
        explode,
        example = json!(["Value"])),
        max_length = 10,
        min_items = 1
    )
)
```

--------------------------------

### AllOfBuilder::example

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/schema.rs.html?search=u32+-%3E+bool

Adds or changes example shown in UI of the value for richer documentation. Deprecated since 3.0.x. Prefer AllOfBuilder::examples instead.

```APIDOC
## AllOfBuilder::example

### Description
Adds or changes example shown in UI of the value for richer documentation. Deprecated since 3.0.x. Prefer AllOfBuilder::examples instead.

### Method
pub fn example(mut self, example: Option<Value>) -> Self

### Parameters
- **example** (Option<Value>) - Optional - The example value to set.

### Returns
Self - The builder instance for chaining.

```

--------------------------------

### on_bright() example

Source: https://docs.rs/utoipa-swagger-ui/latest/utoipa_swagger_ui/struct.BasicAuth.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Sets the quirk to OnBright. Example prints the value with the on_bright quirk applied.

```rust
println!("{}", value.on_bright());
```

--------------------------------

### Config::new()

Source: https://docs.rs/utoipa-swagger-ui/latest/utoipa_swagger_ui/oauth/struct.Config.html?search=

Creates a new Config instance with default settings. The example shows chaining builder methods to set client_id and enable PKCE.

```APIDOC
## Config::new()

### Description
Creates a new Config instance for OAuth settings in Swagger UI. The example demonstrates chaining builder methods to set client_id and enable PKCE.

### Method
new

### Parameters
None

### Request Example
```rust
let config = oauth::Config::new()
    .client_id("client-id")
    .use_pkce_with_authorization_code_grant(true);
```

### Response
#### Success Response
Returns a Config instance with default values.

#### Response Example
```rust
Config {
    client_id: None,
    client_secret: None,
    realm: None,
    app_name: None,
    scope_separator: None,
    scopes: None,
    additional_query_string_params: None,
    use_basic_authentication_with_access_code_grant: None,
    use_pkce_with_authorization_code_grant: None,
}
```
```

--------------------------------

### Create new server with alternative server

Source: https://docs.rs/utoipa/latest/src/utoipa/openapi/server.rs.html

Constructs a Server with an absolute URL 'https://alternative.pet-api.test/api/v1' using the new method.

```rust
# use utoipa::openapi::server::Server;
 Server::new("https://alternative.pet-api.test/api/v1");
```

--------------------------------

### resetting() example

Source: https://docs.rs/utoipa-swagger-ui/latest/utoipa_swagger_ui/struct.BasicAuth.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Sets the quirk to Resetting. Example prints the value with the resetting quirk applied.

```rust
println!("{}", value.resetting());
```

--------------------------------

### linger() example

Source: https://docs.rs/utoipa-swagger-ui/latest/utoipa_swagger_ui/struct.BasicAuth.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Sets the quirk to Linger. Example prints the value with the linger quirk applied.

```rust
println!("{}", value.linger());
```
Tokens:
Raw