Utoipa

https://docs.rs/utoipa/latest/utoipa/
Admin
Utoipa is a Rust library that provides autogenerated OpenAPI documentation for Rust REST APIs,...
Tokens:344,468
Snippets:4,560
Trust Score:9.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### GET /user (multiple examples)

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

An example of providing multiple named examples for a single response body.

```APIDOC
## GET /user

### Description
Retrieves a user. The response includes multiple named examples for documentation purposes.

### Method
GET

### Endpoint
/user

### Response
#### Success Response (200)
- **User** (object) - The user object

#### Examples
- **Demo**: This is summary - Long description
  {
    "name": "Demo"
  }
- **John**: Another user
  {
    "name": "John"
  }
```

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

### Example::new

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

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

```APIDOC
## Example::new

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

### Method
`pub fn new() -> Self`

### Parameters
None.

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

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

### Construct a new Example via builder

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

Example of using `ExampleBuilder::new()` with `.summary()`, `.value()`, and `.build()` to create an `Example`.

```rust
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

Shows how to define multiple examples for a single response using the `examples` attribute. Each example can have a summary, 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()}
}
```

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

### get example

Source: https://docs.rs/utoipa/latest/utoipa/openapi/extensions/struct.Extensions.html

Shows how to retrieve a value by key using the get method. The key may be any borrowed form of the map's key type, but Hash and Eq on the borrowed form must match those for the key type.

```rust
use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
assert_eq!(map.get(&1), Some(&"a"));
assert_eq!(map.get(&2), None);
```

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

### utoipa::path - Multiple Examples

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

Example showing how to provide multiple examples for a single response using the `examples` parameter.

```APIDOC
## utoipa::path Attribute Macro (Multiple Examples)

### Description
Demonstrates documenting multiple examples for a response using the `examples` parameter.

### Usage
Apply the `#[utoipa::path(...)]` attribute to a function.

### Parameters
- **get** (method) - Required - HTTP method.
- **path** (string) - Required - URL path for the endpoint.
- **responses** (array) - Required - Defines response status codes, bodies, and examples.

### Example
```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()}
}
```
```

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

### POST /pet (complete example)

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

A complete example of documenting a POST endpoint with request body, response headers, parameters, security, and an example response.

```APIDOC
## POST /pet

### Description
Creates a new pet and stores it in the database. Demonstrates a complete utoipa::path configuration with request body, response headers, parameters, security, and example.

### Method
POST

### Endpoint
/pet

### Parameters
#### Header Parameters
- **x-csrf-token** (String) - Optional - Current CSRF token of user (deprecated)

#### Request Body
- **Pet** (object) - Required - Pet to store in the database

### Request Example
{
  "id": 1,
  "name": "bob the cat"
}

### Response
#### Success Response (200)
- **Pet** (object) - The stored pet
- **x-cache-len** (String) - Cache length header

#### Response Example
{
  "id": 1,
  "name": "bob the cat"
}

### Security
- No authentication (empty security)
- my_auth: read:items, edit:items
- token_jwt: no scopes
```

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

### POST /pet (minimal example)

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

A minimal example of documenting a POST endpoint with a request body, response headers, and a header parameter.

```APIDOC
## POST /pet

### Description
Creates a new pet with minimal utoipa::path configuration, using defaults for unspecified attributes.

### Method
POST

### Endpoint
/pet

### Parameters
#### Header Parameters
- **x-csrf-token** (String) - Optional - Current CSRF token of user

#### Request Body
- **Pet** (object) - Required - Pet to store

### Response
#### Success Response (200)
- **Pet** (object) - The stored pet
- **x-cache-len** (String) - Cache length header
```

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

### post_pet (Minimal Example)

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

A minimal example of documenting a POST /pet endpoint with a request body, response headers, and parameters.

```APIDOC
## POST /pet

### Description
Creates a new pet. This is a minimal example with defaults.

### Method
POST

### Endpoint
/pet

### Parameters
#### Header Parameters
- **x-csrf-token** (String) - Required - Current csrf token of user

#### Request Body
- **Pet** - Required - Pet object

### Request Example
```json
{
  "id": 4,
  "name": "bob the cat"
}
```

### Response
#### Success Response (200)
- **Pet** - Pet stored successfully
- **x-cache-len** (String) - Cache length

#### Response Example
```json
{
  "id": 4,
  "name": "bob the cat"
}
```
```

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

### Example: path_from with MyPath

Source: https://docs.rs/utoipa/latest/utoipa/openapi/path/struct.PathsBuilder.html?search=

Example usage of the path_from method, appending a Path implementation to the paths.

```rust
let paths = utoipa::openapi::path::PathsBuilder::new();
let _ = paths.path_from::<MyPath>();
```

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

### AnyOfBuilder::example

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

Adds or changes an example shown in UI for richer documentation. Deprecated since OpenAPI 3.1, prefer using `examples`.

```APIDOC
## AnyOfBuilder::example

### Description
Add or change example shown in UI of the value for richer documentation.

**Deprecated since 3.0.x. Prefer `AllOfBuilder::examples` instead**

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

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

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

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

### Example of `examples(...)` attribute definition

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

Shows the syntax for defining a response example using the `examples(...)` attribute. The example defines a single example named "John" with a summary and a JSON value.

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

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

### AnyOfBuilder::example

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

Adds or changes an example shown in the UI for richer documentation. Deprecated since OpenAPI 3.1, prefer using examples.

```APIDOC
## AnyOfBuilder::example

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

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

### Parameters
- `example` (Option<Value>) - Required - The example value to set.

### Returns
- `Self` - The builder with the example set.
```

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

### Example of example definition

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

Shows the syntax for defining an example within the `examples(...)` attribute. The example uses a name, summary, and a JSON value.

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

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

### POST /pet (minimal example)

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

A minimal example of a POST endpoint with request body and response headers.

```APIDOC
## POST /pet

### Description
A minimal example of a POST endpoint with request body and response headers.

### Method
POST

### Endpoint
/pet

### Parameters
#### Header Parameters
- **x-csrf-token** (String) - Optional - Current csrf token of user

#### Request Body
- **Pet** - Required - The pet to store

### Request Example
```rust
#[utoipa::path(
   post,
   path = "/pet",
   request_body = Pet,
   responses(
        (status = 200, description = "Pet stored successfully", body = Pet,
            headers(
                ("x-cache-len", description = "Cache length")
            )
        ),
   ),
   params(
     ("x-csrf-token", Header, description = "Current csrf token of user"),
   )
)]
fn post_pet(pet: Pet) -> Pet {
    Pet {
        id: 4,
        name: "bob the cat".to_string(),
    }
}
```

### Response
#### Success Response (200)
- **body** (Pet) - Pet stored successfully
- **x-cache-len** - Cache length
```

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

### Define response example with summary and JSON value

Source: https://docs.rs/utoipa/latest/utoipa/derive.IntoResponses.html?search=

Shows the syntax for the `examples(...)` attribute of `#[response(...)]`, where each example requires a `name` literal string and can include `summary` and `value` (a `serde_json::json!` value). The `value` attribute is mutually exclusive with `external_value`.

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

```

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

### Simple Pet example with descriptions and object-level example

Source: https://docs.rs/utoipa/latest/utoipa/derive.ToSchema.html

Defines a Pet struct with doc comments as descriptions and an object-level example using `json!`. The example is a JSON object with name, id, and age fields.

```rust
/// This is a pet.
#[derive(ToSchema)]
#[schema(example = json!({"name": "bob the cat", "id": 0}))]
struct Pet {
    /// Unique id of a pet.
    id: u64,
    /// Name of a pet.
    name: String,
    /// Age of a pet if known.
    age: Option<i32>,
}

```

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

### AllOfBuilder::example

Source: https://docs.rs/utoipa/latest/utoipa/openapi/schema/struct.AllOfBuilder.html?search=

Adds or changes example shown in UI of the value for richer documentation. Deprecated since OpenAPI 3.1, prefer `examples`.

```APIDOC
## AllOfBuilder::example

### Description
Add or change example shown in UI of the value for richer documentation.

**Deprecated**: Since OpenAPI 3.1 prefer using `examples`. Deprecated since 3.0.x. Prefer `AllOfBuilder::examples` instead.

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

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

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

```

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

### Example of params with tuples

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

Example of using the `params(...)` attribute with tuple format, demonstrating various attributes like `description`, `deprecated`, `style`, `allow_reserved`, `explode`, `example`, `max_length`, and `min_items`.

```text
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
    )
)
```

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

### BTreeMap::range example

Source: https://docs.rs/utoipa/latest/utoipa/openapi/path/type.Callback.html

Constructs a double-ended iterator over a sub-range of elements. The example uses `(Included(&4), Included(&8))` to iterate over keys 4 through 8 inclusive, and also shows `range(4..)` to get elements from 4 onward. Panics if range start > end or if start == end with both bounds Excluded.

```rust
use std::collections::BTreeMap;
use std::ops::Bound::Included;

let mut map = BTreeMap::new();
map.insert(3, "a");
map.insert(5, "b");
map.insert(8, "c");
for (&key, &value) in map.range((Included(&4), Included(&8))) {
    println!("{key}: {value}");
}
assert_eq!(Some((&5, &"b")), map.range(4..).next());
```

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

### ExampleBuilder::new

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

Constructs a new `ExampleBuilder` instance.

```APIDOC
## ExampleBuilder::new

### Description
Constructs a new `ExampleBuilder` instance.

### Method
new

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

### Parameters
None

### Returns
- **ExampleBuilder** - A new builder instance.

```

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

### get_disjoint_mut panicking example

Source: https://docs.rs/utoipa/latest/utoipa/openapi/extensions/struct.Extensions.html

This example is marked with the warning symbol (ⓘ) indicating it will panic. It shows that calling get_disjoint_mut with overlapping keys causes a panic. The example inserts a single key and then attempts to get mutable references to the same key twice.

```rust
use std::collections::HashMap;

let mut libraries = HashMap::new();
libraries.insert("Athenæum".to_string(), 1807);
```

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

### GET /test-links (response links)

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

An example of using links in a response to reference related operations.

```APIDOC
## GET /test-links

### Description
Returns a success response with links to related operations.

### Method
GET

### Endpoint
/test-links

### Response
#### Success Response (200)
- Description: success response

#### Links
- **getFoo**: operation_id = test_links, parameters: key=value, json_value=1, request_body = "this is body", server: http://localhost
- **getBar**: operation_ref = "this is ref"
```

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

### ComponentsBuilder::example()

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

Adds a reusable `Example` to `Components`.

```APIDOC
## ComponentsBuilder::example()

### Description
Adds a reusable `Example` to `Components`.

### Method
`pub fn example<S: Into<String>, E: Into<RefOr<Example>>>(self, name: S, example: E) -> Self`

### Parameters
- **name** (S) - Required - The name of the example.
- **example** (E) - Required - The example to add.

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

### Example
```rust
let components = ComponentsBuilder::new()
    .example("Accepted", ExampleBuilder::new().summary("Accepted").build())
    .build();
```

```

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

### BTreeMap::entry example

Source: https://docs.rs/utoipa/latest/utoipa/openapi/path/type.Callback.html

Gets the given key's corresponding entry in the map for in-place manipulation. The example counts occurrences of letters in a vector using `entry(x).and_modify(...).or_insert(1)`.

```rust
use std::collections::BTreeMap;

let mut count: BTreeMap<&str, usize> = BTreeMap::new();

// count the number of occurrences of letters in the vec
for x in ["a", "b", "a", "c", "a", "b"] {
    count.entry(x).and_modify(|curr| *curr += 1).or_insert(1);
}

assert_eq!(count["a"], 3);
assert_eq!(count["b"], 2);
assert_eq!(count["c"], 1);
```

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

### ComponentsBuilder::example()

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

Adds a reusable `Example` to `Components`.

```APIDOC
## ComponentsBuilder::example()

### Description
Adds a reusable `Example` to `Components`.

### Method
`pub fn example<S: Into<String>, E: Into<RefOr<Example>>>(self, name: S, example: E) -> Self`

### Parameters
- **name** (S) - Required - The name of the example.
- **example** (E) - Required - The example to add.

### Returns
`Self` for chaining.

### Example
```rust
let components = ComponentsBuilder::new()
    .example("Accepted", ExampleBuilder::new().summary("Accepted").build())
    .build();
```

```

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

### ExampleBuilder::build

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

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

```APIDOC
## ExampleBuilder::build

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

### Method
build

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

### Parameters
None

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

```

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

### GET /api/pet/{id} (context path)

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

An example of using the context_path attribute to prepend a base path to the endpoint.

```APIDOC
## GET /api/pet/{id}

### Description
Retrieves a pet by its ID. The context_path attribute prepends '/api' to the endpoint path.

### Method
GET

### Endpoint
/api/pet/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - Pet id

### Response
#### Success Response (200)
- Description: Pet found from database
```

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

### AnyOfBuilder::examples

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

Adds or changes examples shown in UI for richer documentation.

```APIDOC
## AnyOfBuilder::examples

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

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

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

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

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

### Get user path item

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

Example for `get_path_item` method: returns a reference to the `PathItem` for the given path, or `None` if not found.

```rust
let path_item = paths.get_path_item("/api/v1/user");
```

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

### Get hasher with hasher()

Source: https://docs.rs/utoipa/latest/utoipa/openapi/extensions/struct.Extensions.html

Returns a reference to the map's BuildHasher. The example creates a map with a RandomState hasher and retrieves it.

```rust
use std::collections::HashMap;
use std::hash::RandomState;

let hasher = RandomState::new();
let map: HashMap<i32, i32> = HashMap::with_hasher(hasher);
let hasher: &RandomState = map.hasher();
```

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

### HeaderBuilder::examples_from_iter

Source: https://docs.rs/utoipa/latest/utoipa/openapi/header/struct.HeaderBuilder.html

Adds examples from iterator.

```APIDOC
## HeaderBuilder::examples_from_iter

### Description
Adds examples from iterator.

### Method
`pub fn examples_from_iter<E: IntoIterator<Item = (N, V)>, N: Into<String>, V: Into<RefOr<Example>>>(self, examples: E) -> Self`

### Parameters
- `examples` (E) - Required - An iterator of (name, value) pairs.

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

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

### GET /user (multiple return types)

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

An example of documenting an endpoint that can return different content types based on the Accept header.

```APIDOC
## GET /user

### Description
Retrieves a user. The response can be either User1 or User2 depending on the requested content type.

### Method
GET

### Endpoint
/user

### Response
#### Success Response (200)
- **User1** (object) - Returned when Accept: application/vnd.user.v1+json
- **User2** (object) - Returned when Accept: application/vnd.user.v2+json

#### Response Example
{
  "id": "id"
}

or

{
  "id": 2
}
```

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

### AnyOfBuilder::examples

Source: https://docs.rs/utoipa/latest/utoipa/openapi/schema/struct.AnyOfBuilder.html?search=

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

```APIDOC
## AnyOfBuilder::examples

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

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

### Parameters
- `examples` (`I`) - Required - An iterator of values convertible into `Value`.

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

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

### GET /pet/{id} (deprecated)

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

An example of using Rust's #[deprecated] attribute to mark an endpoint as deprecated in the OpenAPI spec.

```APIDOC
## GET /pet/{id}

### Description
Retrieves a pet by its ID. This operation is marked as deprecated using Rust's #[deprecated] attribute.

### Method
GET

### Endpoint
/pet/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - Pet id

### Response
#### Success Response (200)
- Description: Pet found from database
```

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

### last_key_value: Get maximum key-value pair

Source: https://docs.rs/utoipa/latest/utoipa/openapi/path/type.Callback.html

Returns the last (maximum) key-value pair in the map. Example shows the pair with the largest key.

```rust
use std::collections::BTreeMap;

let mut map = BTreeMap::new();
map.insert(1, "b");
map.insert(2, "a");
assert_eq!(map.last_key_value(), Some((&2, &"a")));
```

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

### AllOfBuilder::examples

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

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

```APIDOC
## AllOfBuilder::examples

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

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

### Parameters
- `examples` (I) - Required - An iterator of example values to set.

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

```

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

### Get user operation from paths

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

Example for `get_path_operation` method: returns a reference to the `Operation` for the given path and HTTP method, or `None` if not found.

```rust
let operation = paths.get_path_operation("/api/v1/user", HttpMethod::Get);
```

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

### AnyOfBuilder::examples

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

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

```APIDOC
## AnyOfBuilder::examples

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

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

### Parameters
- `examples` (I) - Required - An iterator of values convertible into `Value`.

### Returns
- `Self` - The builder with the examples set.
```

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

### HashMap::len example

Source: https://docs.rs/utoipa/latest/utoipa/openapi/extensions/struct.Extensions.html

Shows how to use `HashMap::len` to get the number of elements. The length is 0 initially and 1 after inserting an element.

```rust
use std::collections::HashMap;

let mut a = HashMap::new();
assert_eq!(a.len(), 0);
a.insert(1, "a");
assert_eq!(a.len(), 1);
```

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

### HeaderBuilder::examples_from_iter

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

Adds examples from an iterator.

```APIDOC
## HeaderBuilder::examples_from_iter

### Description
Adds examples from an iterator.

### Method
`pub fn examples_from_iter<E: IntoIterator<Item = (N, V)>, N: Into<String>, V: Into<RefOr<Example>>>(self, examples: E) -> Self`

### Parameters
- `examples` (E) - Required - An iterator of key-value pairs where the key is a string and the value is an example.

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

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

### get_disjoint_mut example

Source: https://docs.rs/utoipa/latest/utoipa/openapi/extensions/struct.Extensions.html

Shows how to get mutable references to multiple values at once. The method returns an array of Option<&mut V>, with None for missing keys. It panics if any keys overlap. The example demonstrates retrieving two values, asserting values, and handling missing keys.

```rust
use std::collections::HashMap;

let mut libraries = HashMap::new();
libraries.insert("Bodleian Library".to_string(), 1602);
libraries.insert("Athenæum".to_string(), 1807);
libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(), 1691);
libraries.insert("Library of Congress".to_string(), 1800);

// Get Athenæum and Bodleian Library
let [Some(a), Some(b)] = libraries.get_disjoint_mut([
    "Athenæum",
    "Bodleian Library",
]) else { panic!() };

// Assert values of Athenæum and Library of Congress
let got = libraries.get_disjoint_mut([
    "Athenæum",
    "Library of Congress",
]);
assert_eq!(
    got,
    [
        Some(&mut 1807),
        Some(&mut 1800),
    ],
);

// Missing keys result in None
let got = libraries.get_disjoint_mut([
    "Athenæum",
    "New York Public Library",
]);
assert_eq!(
    got,
    [
        Some(&mut 1807),
        None
    ]
);
```

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

### get_pet_by_id (Context Path)

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

An example of documenting a GET /pet/{id} endpoint with a context path of /api, resulting in the full path /api/pet/{id}.

```APIDOC
## GET /api/pet/{id}

### Description
Retrieves a pet by its ID. The context path /api is prepended to the endpoint path.

### Method
GET

### Endpoint
/api/pet/{id}

### Parameters
#### Path Parameters
- **id** (i32) - Required - Pet id

### Response
#### Success Response (200)
- Description: Pet found from database
```

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

### get_mut example

Source: https://docs.rs/utoipa/latest/utoipa/openapi/path/type.Callback.html

Demonstrates getting a mutable reference to a value in a BTreeMap and modifying it. The key may be any borrowed form of the map's key type, but the ordering must match.

```rust
use std::collections::BTreeMap;

let mut map = BTreeMap::new();
map.insert(1, "a");
if let Some(x) = map.get_mut(&1) {
    *x = "b";
}
assert_eq!(map[&1], "b");
```

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

### first_key_value: Get minimum key-value pair

Source: https://docs.rs/utoipa/latest/utoipa/openapi/path/type.Callback.html

Returns the first (minimum) key-value pair in the map. Example shows None on empty map and the pair with the smallest key after insertion.

```rust
use std::collections::BTreeMap;

let mut map = BTreeMap::new();
assert_eq!(map.first_key_value(), None);
map.insert(1, "b");
map.insert(2, "a");
assert_eq!(map.first_key_value(), Some((&1, &"b")));
```

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

### AnyOfBuilder::example

Source: https://docs.rs/utoipa/latest/utoipa/openapi/schema/struct.AnyOfBuilder.html?search=

Add or change example shown in UI of the value for richer documentation. Deprecated since OpenAPI 3.1, prefer using `examples`.

```APIDOC
## AnyOfBuilder::example

### Description
Add or change example shown in UI of the value for richer documentation. Deprecated since OpenAPI 3.1, prefer using `examples`.

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

### Parameters
- `example` (`Option<Value>`) - Required - The example value to set.

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

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

### get_mut example

Source: https://docs.rs/utoipa/latest/utoipa/openapi/extensions/struct.Extensions.html

Shows how to get a mutable reference to a value in a HashMap using get_mut. The key may be any borrowed form of the map's key type, but Hash and Eq on the borrowed form must match those for the key type.

```rust
use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
if let Some(x) = map.get_mut(&1) {
    *x = "b";
}
assert_eq!(map[&1], "b");
```

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

### Using #[deprecated] attribute with #[utoipa::path]

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

Shows how Rust's #[deprecated] attribute is reflected in the generated OpenAPI spec, marking the operation as deprecated. The example uses a GET endpoint with a path parameter and returns a JSON response.

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

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

### Implement Path Trait with #[utoipa::path] Macro

Source: https://docs.rs/utoipa/latest/utoipa/trait.Path.html

Example of using the `#[utoipa::path(...)]` attribute macro to implement the `Path` trait for an async function `get_pet_by_id`. It defines a GET endpoint at `/pets/{id}` with responses and a path parameter.

```rust
/// 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(),
    }
}
```

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

### AllOfBuilder::examples

Source: https://docs.rs/utoipa/latest/utoipa/openapi/schema/struct.AllOfBuilder.html?search=

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

```APIDOC
## AllOfBuilder::examples

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

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

### Parameters
- `examples` (I) - Required - An iterator of values convertible into `Value`.

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

```

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

### get: Retrieve value by borrowed key

Source: https://docs.rs/utoipa/latest/utoipa/openapi/path/type.Callback.html

Returns a reference to the value for a given key. The key may be any borrowed form of the map's key type, but ordering must match. Example shows retrieving an existing key and a missing key.

```rust
use std::collections::BTreeMap;

let mut map = BTreeMap::new();
map.insert(1, "a");
assert_eq!(map.get(&1), Some(&"a"));
assert_eq!(map.get(&2), None);
```

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

### AllOfBuilder::example

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

Add or change example shown in UI of the value for richer documentation. Deprecated since OpenAPI 3.1 prefer using `examples`.

```APIDOC
## AllOfBuilder::example

### Description
Add or change example shown in UI of the value for richer documentation. Deprecated since OpenAPI 3.1 prefer using `examples`.

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

### Parameters
- `example` (Option<Value>) - Required - The example value to set.

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

### Deprecation
Deprecated since 3.0.x. Prefer `AllOfBuilder::examples` instead.

```
Tokens:
Raw