Poem OpenAPI

https://docs.rs/poem-openapi/latest/
Admin
Poem OpenAPI is a Rust library that enables easy implementation of APIs compliant with the OpenAPI...
Tokens:371,947
Snippets:3,101
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Hello World Example

Source: https://docs.rs/poem-openapi/latest/poem_openapi/index.html

A basic example demonstrating how to set up a simple API with Poem and poem-openapi, including a root endpoint that returns 'Hello World'.

```APIDOC
## GET /

### Description
Returns a simple "Hello World" message.

### Method
GET

### Endpoint
/

### Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **body** (PlainText) - The "Hello World" message.

### Response Example
```
Hello World
```
```

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

### Rust Example: Uploading and Streaming Binary Data

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/payload/binary.rs.html

Demonstrates how to define API endpoints for uploading binary data as `Binary<Vec<u8>>` and streaming it as `Binary<Body>`. Includes setup with `poem_openapi` and `TestClient` for testing.

```rust
use poem::{
    Body, IntoEndpoint, Request, Result,
    error::BadRequest,
    http::{Method, StatusCode, Uri},
    test::TestClient,
};
use poem_openapi::{
    OpenApi, OpenApiService,
    payload::{Binary, Json},
};
use tokio::io::AsyncReadExt;

struct MyApi;

#[OpenApi]
impl MyApi {
    #[oai(path = "/upload", method = "post")]
    async fn upload_binary(&self, data: Binary<Vec<u8>>) -> Json<usize> {
        Json(data.len())
    }

    #[oai(path = "/upload_stream", method = "post")]
    async fn upload_binary_stream(&self, data: Binary<Body>) -> Result<Json<usize>> {
        let mut reader = data.0.into_async_read();
        let mut bytes = Vec::new();
        reader.read_to_end(&mut bytes).await.map_err(BadRequest)?;
        Ok(Json(bytes.len()))
    }
}

let api = OpenApiService::new(MyApi, "Demo", "0.1.0");
let cli = TestClient::new(api);

# tokio::runtime::Runtime::new().unwrap().block_on(async {
let resp = cli
    .post("/upload")
    .content_type("application/octet-stream")
    .body("abcdef")
    .send()
    .await;
resp.assert_status_is_ok();
resp.assert_text("6").await;

let resp = cli
    .post("/upload_stream")
    .content_type("application/octet-stream")
    .body("abcdef")
    .send()
    .await;
resp.assert_status_is_ok();
resp.assert_text("6").await;
# });

```

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

### Example Usage

Source: https://docs.rs/poem-openapi/latest/poem_openapi/attr.Webhook.html

Example of how to define and use a webhook with poem-openapi.

```APIDOC
## Examples

```rust
use poem_openapi::{Object, Webhook, payload::Json, OpenApiService};

#[derive(Object)]
struct Pet {
    id: i64,
    name: String,
}

#[Webhook]
trait MyWebhooks {
    /// This is the summary of the operation
    ///
    /// This is the description of the operation
    #[oai(method = "post")]
    fn new_pet(&self, pet: Json<Pet>);
}

let api = OpenApiService::new((), "Demo", "1.0.0")
    .webhooks::<&dyn MyWebhooks>();
```
```

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

### Hello World Example

Source: https://docs.rs/poem-openapi/latest/index.html

A basic example demonstrating how to set up a simple "Hello World" API using poem-openapi. This includes defining an API structure, implementing an endpoint, and serving the API with Swagger UI.

```APIDOC
## GET /

### Description
Responds with a simple "Hello World" message.

### Method
GET

### Endpoint
/

### Request Body
None

### Response
#### Success Response (200)
- **body** (PlainText<&'static str>) - The "Hello World" message.

### Request Example
None

### Response Example
```
Hello World
```
```

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

### Base64 Payload Usage Example

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/payload/base64_payload.rs.html

Demonstrates how to use `Base64` for uploading and downloading binary data in a Poem OpenAPI service. It shows receiving base64 encoded data in a POST request and returning base64 encoded data in a GET response.

```APIDOC
## POST /upload

### Description
Uploads binary data encoded in Base64.

### Method
POST

### Endpoint
/upload

### Parameters
#### Request Body
- **data** (Base64<Vec<u8>>) - Required - The binary data encoded as a Base64 string.

### Request Example
```http
POST /upload HTTP/1.1
Content-Type: text/plain

YWJjZGVm
```

### Response
#### Success Response (200)
- **body** (Json<usize>) - The length of the uploaded binary data.

#### Response Example
```http
HTTP/1.1 200 OK
Content-Type: application/json

6
```

## GET /download

### Description
Downloads binary data encoded in Base64.

### Method
GET

### Endpoint
/download

### Response
#### Success Response (200)
- **body** (Base64<Vec<u8>>) - The binary data encoded as a Base64 string.

#### Response Example
```http
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

YWJjZGVm
```
```

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

### Example of capacity()

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Email.html

Returns this String’s capacity in bytes. Useful for understanding memory allocation.

```rust
let s = String::with_capacity(10);

assert!(s.capacity() >= 10);
```

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

### Upload Binary Data Example

Source: https://docs.rs/poem-openapi/latest/poem_openapi/payload/struct.Binary.html

Demonstrates uploading binary data as Vec<u8> using the Binary payload and testing the response.

```rust
use poem::{
    Body,
    IntoEndpoint,
    Request,
    Result,
    error::BadRequest,
    http::{Method, StatusCode, Uri},
    test::TestClient,
};
use poem_openapi::*
use poem_openapi::payload::{Binary, Json};
use tokio::io::AsyncReadExt;

struct MyApi;

#[OpenApi]
impl MyApi {
    #[oai(path = "/upload", method = "post")]
    async fn upload_binary(&self, data: Binary<Vec<u8>>) -> Json<usize> {
        Json(data.len())
    }

    #[oai(path = "/upload_stream", method = "post")]
    async fn upload_binary_stream(&self, data: Binary<Body>) -> Result<Json<usize>> {
        let mut reader = data.0.into_async_read();
        let mut bytes = Vec::new();
        reader.read_to_end(&mut bytes).await.map_err(BadRequest)?;
        Ok(Json(bytes.len()))
    }
}

let api = OpenApiService::new(MyApi, "Demo", "0.1.0");
let cli = TestClient::new(api);

let resp = cli
    .post("/upload")
    .content_type("application/octet-stream")
    .body("abcdef")
    .send()
    .await;
resp.assert_status_is_ok();
resp.assert_text("6").await;

let resp = cli
    .post("/upload_stream")
    .content_type("application/octet-stream")
    .body("abcdef")
    .send()
    .await;
resp.assert_status_is_ok();
resp.assert_text("6").await;
```

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

### Example Usage of #[OpenApi] with prefix_path and tag

Source: https://docs.rs/poem-openapi/latest/poem_openapi/attr.OpenApi.html

Demonstrates how to use the `#[OpenApi]` attribute with `prefix_path` and `tag` to define an API endpoint.

```APIDOC
### §Example
```rust
use poem_openapi::{OpenApi, Tags};
use poem_openapi::param::Path;
use poem_openapi::payload::PlainText;

#[derive(Tags)]
enum MyTags {
    V1
}

struct Api;

#[OpenApi(prefix_path = "/v1/:customer_id", tag = "MyTags::V1")]
impl Api {
    /// Greet the customer
    ///
    /// # Example
    /// 
    /// Call `/v1/1234/hello` to get the response `"Hello 1234!"`. 
    #[oai(path = "/hello", method = "get")]
    async fn hello(&self, customer_id: Path<String>) -> PlainText<String> {
        PlainText(format!("Hello {}!", customer_id.0))
    }
}
```
```

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

### Define the Example Trait

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/trait.Example.html

This trait defines a required method `example()` that must be implemented by types that represent an example. It is not dyn compatible.

```rust
pub trait Example {
    // Required method
    fn example() -> Self;
}
```

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

### Multiple Authentication Methods Example

Source: https://docs.rs/poem-openapi/latest/poem_openapi/derive.SecurityScheme.html

Illustrates how to define multiple authentication methods using an enum with the `SecurityScheme` derive macro.

```APIDOC
## Multiple Authentication Methods
When `SecurityScheme` macro is used with an enumerated type, it is used to define multiple authentication methods.
```rust
use poem_openapi::{OpenApi, SecurityScheme};
use poem_openapi::payload::PlainText;
use poem_openapi::auth::{ApiKey, Basic};

#[derive(SecurityScheme)]
#[oai(ty = "basic")]
struct MySecurityScheme1(Basic);

#[derive(SecurityScheme)]
#[oai(ty = "api_key", key_name = "X-API-Key", key_in = "header")]
struct MySecurityScheme2(ApiKey);

#[derive(SecurityScheme)]
enum MySecurityScheme {
    MySecurityScheme1(MySecurityScheme1),
    MySecurityScheme2(MySecurityScheme2),
}

struct MyApi;

#[OpenApi]
impl MyApi {
    #[oai(path = "/test", method = "get")]
    async fn test(&self, auth: MySecurityScheme) -> PlainText<String> {
        match auth {
            MySecurityScheme::MySecurityScheme1(auth) => {
                PlainText(format!("basic: {}", auth.0.username))
            }
            MySecurityScheme::MySecurityScheme2(auth) => {
                PlainText(format!("api-key: {}", auth.0.key))
            }
        }
    }
}
```
```

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

### Example of ResponseContent Enum Usage

Source: https://docs.rs/poem-openapi/latest/poem_openapi/derive.ResponseContent.html

This example demonstrates how to use the `ResponseContent` derive macro with an enum that includes different payload types like Json, PlainText, and Binary. It also shows how to integrate this with `ApiResponse`.

```rust
use poem_openapi::{
    payload::{Binary, Json, PlainText},
    ApiResponse,
    ResponseContent,
};

#[derive(ResponseContent)]
enum MyResponseContent {
    A(Json<i32>),
    B(PlainText<String>),
    C(Binary<Vec<u8>>),
}

#[derive(ApiResponse)]
enum MyResponse {
    #[oai(status = 200)]
    Ok(MyResponseContent),
}
```

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

### Example: Creating and Configuring an EventStream

Source: https://docs.rs/poem-openapi/latest/poem_openapi/payload/struct.EventStream.html

Demonstrates how to create an EventStream from an iterator, convert its items into JSON strings, and format them as SSE events with a specific event type.

```rust
use poem::web::sse::Event;
use poem_openapi::{Object, payload::EventStream, types::ToJSON};

#[derive(Debug, Object)]
struct MyEvent {
    value: i32,
}

EventStream::new(futures_util::stream::iter(vec![ 
    MyEvent { value: 1 },
    MyEvent { value: 2 },
    MyEvent { value: 3 },
]))
.to_event(|event| {
    let json = event.to_json_string();
    Event::message(json).event_type("push")
});
```

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

### Example Usage of #[OpenApi] with operation-level tag

Source: https://docs.rs/poem-openapi/latest/poem_openapi/attr.OpenApi.html

Illustrates using the `#[OpenApi]` attribute with an operation-level `tag` parameter.

```APIDOC
### §Example
```rust
use poem_openapi::{OpenApi, Tags};
use poem_openapi::param::Path;
use poem_openapi::payload::PlainText;

#[derive(Tags)]
enum MyTags {
    V1
}

struct Api;

#[OpenApi]
impl Api {
    /// Greet the customer
    ///
    /// # Example
    /// 
    /// Call `/v1/1234/hello` to get the response `"Hello 1234!"`. 
    #[oai(path = "/v1/:customer_id/hello", method = "get", tag = "MyTags::V1")]
    async fn hello(&self, customer_id: Path<String>) -> PlainText<String> {
        PlainText(format!("Hello {}!", customer_id.0))
    }
}
```
```

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

### Example of push_str()

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Email.html

Appends a given string slice onto the end of this String. Available on non-`no_global_oom_handling` only. Panics if the new capacity exceeds `isize::MAX` bytes.

```rust
let mut s = String::from("foo");

s.push_str("bar");

assert_eq!("foobar", s);
```

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

### LicenseObject::new

Source: https://docs.rs/poem-openapi/latest/poem_openapi/struct.LicenseObject.html

Creates a new LicenseObject with the given name. This is the starting point for defining license information.

```APIDOC
## LicenseObject::new

### Description
Creates a license object by name.

### Signature
```rust
pub fn new(name: impl Into<String>) -> LicenseObject
```

### Parameters
* `name` (impl Into<String>) - The name of the license.
```

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

### Example of reserve()

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Email.html

Reserves capacity for at least additional bytes more than the current length. Available on non-`no_global_oom_handling` only. Panics if the new capacity exceeds `isize::MAX` bytes.

```rust
let mut s = String::new();

s.reserve(10);

assert!(s.capacity() >= 10);
```

```rust
let mut s = String::with_capacity(10);
s.push('a');
s.push('b');

let capacity = s.capacity();
assert_eq!(2, s.len());
assert!(capacity >= 10);

s.reserve(8);

assert_eq!(capacity, s.capacity());
```

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

### Response Constructor

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/payload/response.rs.html

Provides a constructor for the `Response` struct, initializing it with a given payload. This is the starting point for creating a new response object.

```rust
impl<T> Response<T> {
    /// Create a response object.
    #[must_use]
    pub fn new(resp: T) -> Self {
        Self {
            inner: resp,
            status: None,
            headers: HeaderMap::new(),
        }
    }
```

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

### Experimental: Get substring range indices

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Email.html

This is a nightly-only experimental API. It splits a string by a pattern and returns an iterator yielding the start and end byte indices of each matched substring within the original string.

```rust
#![feature(substr_range)]

let data = "a, b, b, a";
let mut iter = data.split(", ").map(|s| data.substr_range(s).unwrap());

assert_eq!(iter.next(), Some(0..1));
assert_eq!(iter.next(), Some(3..4));
assert_eq!(iter.next(), Some(6..7));
assert_eq!(iter.next(), Some(9..10));
```

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

### Normalize Path String

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/path_util.rs.html

Ensures a path string starts with a '/' and handles empty paths by returning '/'. Useful for standardizing path inputs.

```rust
fn normalize_path(path: &str) -> String {
    if path.is_empty() {
        "/".to_string()
    } else if !path.starts_with('/') {
        format!("/{path}")
    } else {
        path.to_string()
    }
}
```

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

### Basic Hello World API with Poem OpenAPI

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/lib.rs.html

This example demonstrates a simple "Hello World" API using Poem and poem-openapi. It defines a basic API structure, an index endpoint, and sets up the server with Swagger UI integration.

```rust
use poem::{listener::TcpListener, Route, Server};
use poem_openapi::{payload::PlainText, OpenApi, OpenApiService};

struct Api;

#[OpenApi]
impl Api {
    /// Hello world
    #[oai(path = "/", method = "get")]
    async fn index(&self) -> PlainText<&'static str> {
        PlainText("Hello World")
    }
}

#[tokio::main]
async fn main() {
    let api_service = 
        OpenApiService::new(Api, "Hello World", "1.0").server("http://localhost:3000");
    let ui = api_service.swagger_ui();
    let app = Route::new().nest("/", api_service).nest("/docs", ui);

    Server::new(TcpListener::bind("127.0.0.1:3000"))
        .run(app)
        .await;
}

```

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

### Example of reserve_exact()

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Email.html

Reserves the minimum capacity for at least additional bytes more than the current length. Available on non-`no_global_oom_handling` only. Panics if the new capacity exceeds `isize::MAX` bytes.

```rust
let mut s = String::new();

s.reserve_exact(10);

assert!(s.capacity() >= 10);
```

```rust
let mut s = String::with_capacity(10);
s.push('a');
s.push('b');

let capacity = s.capacity();
assert_eq!(2, s.len());
assert!(capacity >= 10);

s.reserve_exact(8);

assert_eq!(capacity, s.capacity());
```

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

### Example Trait Definition

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/types/mod.rs.html

Defines a generic `Example` trait with a single method `example()` that returns an instance of the implementing type. This is likely used for providing example data.

```rust
pub trait Example {
    /// Returns the example object
    fn example() -> Self;
}
```

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

### Initialize Registry

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/registry/mod.rs.html

Creates a new, empty Registry instance.

```rust
pub fn new() -> Self {
    Default::default()
}
```

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

### Basic API Implementation

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/lib.rs.html

Demonstrates a simple 'Hello World' API endpoint using Poem and poem-openapi. This includes setting up the API structure, defining an endpoint with OpenAPI attributes, and running the server.

```APIDOC
## GET /

### Description
Provides a simple "Hello World" response.

### Method
GET

### Endpoint
/

### Request Body
None

### Response
#### Success Response (200)
- **body** (PlainText<&'static str>) - The "Hello World" message.

### Request Example
None

### Response Example
```text
Hello World
```
```

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

### Rust nightly substr_range example

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Hostname.html

This example demonstrates the usage of the `substr_range` method, which is a nightly-only experimental API. It returns the byte range of a substring within the original string.

```rust
#![feature(substr_range)]

let data = "a, b, b, a";
let mut iter = data.split(", ").map(|s| data.substr_range(s).unwrap());

assert_eq!(iter.next(), Some(0..1));
assert_eq!(iter.next(), Some(3..4));
assert_eq!(iter.next(), Some(6..7));
assert_eq!(iter.next(), Some(9..10));

```

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

### Example of try_reserve()

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Email.html

Tries to reserve capacity for at least additional bytes more than the current length. Returns a Result indicating success or failure due to capacity overflow or allocation errors.

```rust
let mut s = String::with_capacity(10);

// Example of successful reservation (assuming enough memory)
let result = s.try_reserve(5);
assert!(result.is_ok());
assert!(s.capacity() >= 15);

// Example that might fail if capacity overflows (highly unlikely in practice for small values)
// let large_additional: usize = usize::MAX / 2;
// let fail_result = s.try_reserve(large_additional);
// assert!(fail_result.is_err());
```

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

### Example Union without Discriminator

Source: https://docs.rs/poem-openapi/latest/poem_openapi/derive.Union.html

Defines a union type `MyObj` with three variants: `A` (a struct), `B` (a boolean), and `C` (a string). This example demonstrates a union where an explicit discriminator is not specified.

```rust
use poem_openapi::{Object, Union};

#[derive(Object, Debug, PartialEq)]
struct A {
    v1: i32,
    v2: String,
}

#[derive(Union, Debug, PartialEq)]
enum MyObj {
    A(A),
    B(bool),
    C(String),
}
```

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

### Get Mutable Raw Pointer to String Slice

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Hostname.html

Use `as_mut_ptr` to get a mutable raw pointer to the first byte of a string slice. Modifications must maintain UTF-8 validity.

```rust
let mut s = String::from("hello");
let ptr = s.as_mut_ptr();
// Note: The actual modification would happen here using the pointer.
```

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

### Create a Server Object

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/openapi.rs.html

Use `ServerObject::new` to create a server object with a URL. Chain methods like `description` and `variable` to configure it further.

```rust
impl<T: Into<String>> From<T> for ServerObject {
    fn from(url: T) -> Self {
        Self::new(url)
    }
}

impl ServerObject {
    /// Create a server object by url.
    pub fn new(url: impl Into<String>) -> ServerObject {
        Self {
            url: url.into(),
            description: None,
            variables: BTreeMap::new(),
        }
    }

    /// Sets an string describing the host designated by the URL.
    #[must_use]
    pub fn description(self, description: impl Into<String>) -> Self {
        Self {
            description: Some(description.into()),
            ..self
        }
    }

    /// Adds a server variable with a limited set of values.
    ///
    /// The variable name must be present in the server URL in curly braces.
    #[must_use]
    pub fn enum_variable(
        mut self,
        name: impl Into<String>,
        description: impl Into<String>,
        default: impl Into<String>,
        enum_values: Vec<impl Into<String>>,
    ) -> Self {
        self.variables.insert(
            name.into(),
            MetaServerVariable {
                description: description.into(),
                default: default.into(),
                enum_values: enum_values.into_iter().map(Into::into).collect(),
            },
        );
        self
    }

    /// Adds a server variable that can take any value.
    ///
    /// The variable name must be present in the server URL in curly braces.
    #[must_use]
    pub fn variable(
        mut self,
        name: impl Into<String>,
        description: impl Into<String>,
        default: impl Into<String>,
    ) -> Self {
        self.variables.insert(
            name.into(),
            MetaServerVariable {
                description: description.into(),
                default: default.into(),
                enum_values: Vec::new(),
            },
        );
        self
    }
}
```

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

### OpenApiService::new

Source: https://docs.rs/poem-openapi/latest/poem_openapi/struct.OpenApiService.html

Creates a new OpenApiService instance, initializing the OpenAPI container with the provided API, title, and version.

```APIDOC
## OpenApiService::new

### Description
Create an OpenAPI container.

### Signature
```rust
pub fn new(api: T, title: impl Into<String>, version: impl Into<String>) -> Self
```
```

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

### Safely Get String Subslice

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Email.html

The `get` method returns an `Option<&str>` representing a subslice. It returns `None` if the indices are out of bounds or do not fall on UTF-8 character boundaries, preventing panics.

```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```

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

### Safely get Err value with into_err

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/type.ParseResult.html

Use `into_err` to get the contained `Err` value. This method is guaranteed not to panic and serves as a compile-time safeguard against changes that might introduce panics.

```rust
fn only_bad_news() -> Result<!, String> {
    Err("Oops, it failed".into())
}

let error: String = only_bad_news().into_err();
println!("{error}");
```

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

### Safely get Ok value with into_ok

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/type.ParseResult.html

Use `into_ok` to get the contained `Ok` value. This method is guaranteed not to panic and can be used as a compile-time safeguard against future changes that might introduce panics.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

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

### sample

Source: https://docs.rs/poem-openapi/latest/poem_openapi/payload/struct.Binary.html

Sample a new value, using the given distribution.

```APIDOC
## fn sample<T, D>(&mut self, distr: D) -> T

### Description
Sample a new value, using the given distribution.

### Type Parameters
- `T`: The type of the value to sample.
- `D`: The type of the distribution, which must implement `Distribution<T>`.

### Parameters
- `distr`: The distribution to use for sampling.
```

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

### Product Implementation for Result

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/type.ParseResult.html

Demonstrates how to use the `product` method on an iterator of Results. It calculates the product of successful values, short-circuiting and returning the first error encountered.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
```

```rust
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

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

### get

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Password.html

Returns a subslice of `str` without panicking.

```APIDOC
## get

### Description
Returns a subslice of `str`. This is the non-panicking alternative to indexing the `str`. Returns `None` whenever equivalent indexing operation would panic.

### Method
`get<I>(&self, i: I) -> Option<&<I as SliceIndex<str>>::Output> where I: SliceIndex<str>`

### Examples
```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```
```

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

### OpenApiService::new

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/openapi.rs.html

Creates a new OpenApiService instance with the provided API implementation, title, and version.

```APIDOC
## OpenApiService::new

### Description
Creates a new OpenAPI container with the given API implementation, title, and version.

### Signature
```rust
pub fn new(api: T, title: impl Into<String>, version: impl Into<String>) -> Self
```

### Parameters
- `api`: The API implementation.
- `title`: The title of the API.
- `version`: The version of the API.
```

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

### Get Upload Size

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/multipart/struct.Upload.html

Returns the size of the uploaded file in bytes.

```rust
pub fn size(&self) -> usize
```

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

### Any Trait Implementation for T

Source: https://docs.rs/poem-openapi/latest/poem_openapi/auth/struct.Bearer.html

Provides a method to get the TypeId of a type, part of the Any trait.

```rust
fn type_id(&self) -> TypeId
```

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

### Attachment Creation and Configuration

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/payload/attachment.rs.html

Provides methods to create and configure an `Attachment`. Use `new` to create with data, `attachment_type` to set display behavior, and `filename` to specify the downloaded file's name.

```rust
/// Create an attachment with data.
pub fn new(data: T) -> Self {
    Self {
        data: Binary(data),
        ty: AttachmentType::Attachment,
        filename: None,
    }
}

/// Specify the attachment. (defaults to: [`AttachmentType::Inline`])
#[must_use]
pub fn attachment_type(self, ty: AttachmentType) -> Self {
    Self { ty, ..self }
}

/// Specify the file name.
#[must_use]
pub fn filename(self, filename: impl Into<String>) -> Self {
    Self {
        filename: Some(filename.into()),
        ..self
    }
}
```

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

### Example Usage of MaybeUndefined in API Endpoint

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/types/maybe_undefined.rs.html

Demonstrates how to use MaybeUndefined in an API endpoint to handle updates to a resource. It shows how to match on the different states of MaybeUndefined (Undefined, Null, Value) to update the resource's attributes accordingly. This example requires setting up a basic API service with Poem and Poem OpenAPI.

```rust
use std::{borrow::Cow, ops::Deref};

use poem::{http::HeaderValue, web::Field as PoemField};
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use serde_json::Value;

use crate::{
    registry::{MetaSchemaRef, Registry},
    types::{
        ParseError, ParseFromJSON, ParseFromMultipartField, ParseFromParameter, ParseResult,
        ToHeader, ToJSON, Type,
    },
};

/// Similar to `Option`, but it has three states, `undefined`, `null` and `x`.
///
/// # Example
///
/// ```
/// use poem::{test::TestClient, IntoEndpoint};
/// use poem_openapi::{payload::Json, types::MaybeUndefined, Object, OpenApi, OpenApiService};
/// use tokio::sync::Mutex;
/// use serde_json::json;
///
/// #[derive(Object, Clone, Default)]
/// struct Resource {
///     attr1: Option<i32>,
///     attr2: Option<String>,
/// }
///
/// #[derive(Object)]
/// struct UpdateResourceRequest {
///     attr1: MaybeUndefined<i32>,
///     attr2: MaybeUndefined<String>,
/// }
///
/// struct Api {
///     resource: Mutex<Resource>,
/// }
///
/// #[OpenApi]
/// impl Api {
///     #[oai(path = "/get", method = "get")]
///     async fn get_resource(&self) -> Json<Resource> {
///         Json(self.resource.lock().await.clone())
///     }
///
///     #[oai(path = "/put", method = "put")]
///     async fn update_resource(&self, req: Json<UpdateResourceRequest>) {
///         let mut resource = self.resource.lock().await;
///
///         match req.0.attr1 {
///             MaybeUndefined::Null => resource.attr1 = None,
///             MaybeUndefined::Value(value) => resource.attr1 = Some(value),
///             MaybeUndefined::Undefined => {} // No change if undefined
///         }
///
///         match req.0.attr2 {
///             MaybeUndefined::Null => resource.attr2 = None,
///             MaybeUndefined::Value(value) => resource.attr2 = Some(value),
///             MaybeUndefined::Undefined => {} // No change if undefined
///         }
///     }
/// }
///
/// let api_service = OpenApiService::new(
///     Api {
///         resource: Default::default(),
///     },
///     "Test",
///     "1.0",
/// );
///
/// let cli = TestClient::new(api_service.into_endpoint());
///
/// # tokio::runtime::Runtime::new().unwrap().block_on(async {
/// cli.get("/get").send().await.assert_json(json!({{"attr1": null, "attr2": null}}));
///
/// cli.put("/put").body_json(&json!({{"attr1": 100i32}})).send().await.assert_status_is_ok();
/// cli.get("/get").send().await.assert_json(json!({{"attr1": 100i32, "attr2": null}}));
///
/// cli.put("/put").body_json(&json!({{"attr1": null, "attr2": "abc"}})).send().await.assert_status_is_ok();
/// cli.get("/get").send().await.assert_json(json!({{"attr1": null, "attr2": "abc"}}));
/// # });
/// ```
#[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)]
pub enum MaybeUndefined<T> {
    /// Undefined
    Undefined,
    /// Null
    Null,
    /// Value
    Value(T),
}

impl<T> Default for MaybeUndefined<T> {
    fn default() -> Self {
        Self::Undefined
    }
}

impl<T> From<T> for MaybeUndefined<T> {
    fn from(value: T) -> Self {
        MaybeUndefined::Value(value)
    }
}

impl<T> IntoIterator for MaybeUndefined<T> {
    type Item = T;
    type IntoIter = std::option::IntoIter<T>;

    fn into_iter(self) -> Self::IntoIter {
        self.take().into_iter()
    }
}

impl<T> MaybeUndefined<T> {
    /// Create a `MaybeUndefined<T>` from `Option<T>`, returns
    /// `MaybeUndefined::Undefined` if this value is none.
    pub fn from_opt_undefined(value: Option<T>) -> Self {
        match value {
            Some(value) => MaybeUndefined::Value(value),
            None => MaybeUndefined::Undefined,
        }
    }

    /// Create a `MaybeUndefined<T>` from `Option<T>`, returns
    /// `MaybeUndefined::Null` if this value is none.
    pub fn from_opt_null(value: Option<T>) -> Self {
        match value {
            Some(value) => MaybeUndefined::Value(value),
            None => MaybeUndefined::Null,
        }
    }

    /// Returns true if the `MaybeUndefined<T>` is undefined.
    #[inline]
    pub const fn is_undefined(&self) -> bool {
        matches!(self, MaybeUndefined::Undefined)
    }

    /// Returns true if the `MaybeUndefined<T>` is null.
    #[inline]
    pub const fn is_null(&self) -> bool {
        matches!(self, MaybeUndefined::Null)
    }

    /// Returns true if the `MaybeUndefined<T>` contains value.
    #[inline]
    pub const fn is_value(&self) -> bool {
        matches!(self, MaybeUndefined::Value(_))
    }

    /// Returns `None` if the the `MaybeUndefined<T>` is
    /// `undefined` or `null`, otherwise returns `Some(&T)`.

```

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

### Create a Contact Object

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/openapi.rs.html

Use `ContactObject::new` to initialize a contact object. Configure name, URL, and email using dedicated methods.

```rust
impl ContactObject {
    /// Create a new Contact object
    #[inline]
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets the identifying name of the contact person/organization.
    #[must_use]
    pub fn name(self, name: impl Into<String>) -> Self {
        Self {
            name: Some(name.into()),
            ..self
        }
    }

    /// Sets the URL pointing to the contact information.
    #[must_use]
    pub fn url(self, url: impl Into<String>) -> Self {
        Self {
            url: Some(url.into()),
            ..self
        }
    }

    /// Sets the email address of the contact person/organization.
    #[must_use]
    pub fn email(self, email: impl Into<String>) -> Self {
        Self {
            email: Some(email.into()),
            ..self
        }
    }
}
```

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

### get

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Hostname.html

Safely retrieves a subslice of the string, returning `None` if the indices are invalid or out of bounds.

```APIDOC
## get

### Description
Returns a subslice of `str`. This is the non-panicking alternative to indexing the `str`. Returns `None` whenever equivalent indexing operation would panic.

### Method
`fn get<I>(&self, i: I) -> Option<&<I as SliceIndex<str>>::Output>` where I: SliceIndex<str>

### Parameters
#### Path Parameters
- **i** (I) - The range or index to slice the string with.

### Response
#### Success Response (Option<&<I as SliceIndex<str>>::Output>)
- Returns `Some` containing the subslice if the indices are valid, otherwise `None`.

### Request Example
```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```
```

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

### Create a License Object

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/openapi.rs.html

Create a `LicenseObject` using `LicenseObject::new` with a name. Optionally set an identifier or URL.

```rust
impl<T: Into<String>> From<T> for LicenseObject {
    fn from(url: T) -> Self {
        Self::new(url)
    }
}

impl LicenseObject {
    /// Create a license object by name.
    pub fn new(name: impl Into<String>) -> LicenseObject {
        Self {
            name: name.into(),
            identifier: None,
            url: None,
        }
    }

    /// Sets the [`SPDX`](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API.
    #[must_use]
    pub fn identifier(self, identifier: impl Into<String>) -> Self {
        Self {
            identifier: Some(identifier.into()),
            ..self
        }
    }
}
```

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

### Get Optional Value from MaybeUndefined

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/types/maybe_undefined.rs.html

Returns `Some(&T)` if the `MaybeUndefined<T>` is `Value(T)`, otherwise returns `None`.

```rust
pub const fn value(&self) -> Option<&T> {
        match self {
            MaybeUndefined::Value(value) => Some(value),
            _ => None,
        }
    }
```

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

### OpenApiService::redoc_html

Source: https://docs.rs/poem-openapi/latest/poem_openapi/struct.OpenApiService.html

Creates the Redoc HTML. Available only on `crate feature`redoc`.

```APIDOC
## OpenApiService::redoc_html

### Description
Create the Redoc HTML

### Availability
Available on **crate feature`redoc`** only.

### Signature
```rust
pub fn redoc_html(&self) -> String
where T: OpenApi, W: Webhook
```
```

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

### Get Upload File Name

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/multipart/struct.Upload.html

Retrieves the file name from the Content-Disposition header of the upload.

```rust
pub fn file_name(&self) -> Option<&str>
```

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

### Create ServerObject with URL

Source: https://docs.rs/poem-openapi/latest/poem_openapi/struct.ServerObject.html

Use this function to create a new ServerObject instance, providing the server's URL.

```rust
pub fn new(url: impl Into<String>) -> ServerObject
```

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

### Set Server Description

Source: https://docs.rs/poem-openapi/latest/poem_openapi/struct.ServerObject.html

Add a descriptive string to the ServerObject to explain the host designated by the URL.

```rust
pub fn description(self, description: impl Into<String>) -> Self
```

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

### Get Upload Content Type

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/multipart/struct.Upload.html

Retrieves the content type of the uploaded file, if available.

```rust
pub fn content_type(&self) -> Option<&str>
```

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

### Create OpenAPI Explorer Endpoint (with openapi-explorer feature)

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/openapi.rs.html

Generates an `Endpoint` that serves the OpenAPI Explorer UI. Requires the `openapi-explorer` feature.

```rust
pub fn openapi_explorer(&self) -> impl Endpoint + 'static
    where
        T: OpenApi,
        W: Webhook,
    {
        crate::ui::openapi_explorer::create_endpoint(self.spec())
    }
```

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

### Upload Binary Stream

Source: https://docs.rs/poem-openapi/latest/poem_openapi/payload/struct.Binary.html

Demonstrates how to upload binary data as a stream using the Binary payload with `poem::Body`.

```APIDOC
## POST /upload_stream

### Description
Uploads binary data as a stream and returns its size.

### Method
POST

### Endpoint
/upload_stream

### Request Body
- **data** (Binary<Body>) - Required - The binary data stream to upload.

### Response
#### Success Response (200)
- **response** (Result<Json<usize>>) - The size of the uploaded binary data stream.

### Request Example
```json
{
  "example": "application/octet-stream"
}
```

### Response Example
```json
{
  "example": 6
}
```
```

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

### Payload Implementations

Source: https://docs.rs/poem-openapi/latest/poem_openapi/payload/trait.Payload.html

Examples of types that implement the `Payload` trait, showcasing their specific content types.

```APIDOC
### impl<T: Type> Payload for Form<T>

#### const CONTENT_TYPE: &'static str = "application/x-www-form-urlencoded"

### impl<T: Type> Payload for Json<T>

#### const CONTENT_TYPE: &'static str = "application/json; charset=utf-8"

### impl<T: Type> Payload for Xml<T>

#### const CONTENT_TYPE: &'static str = "application/xml; charset=utf-8"

### impl<T: Type> Payload for Yaml<T>

#### const CONTENT_TYPE: &'static str = "application/yaml; charset=utf-8"

### impl<T: Into<Body> + Send> Payload for Attachment<T>

#### const CONTENT_TYPE: &'static str = Binary<T>::CONTENT_TYPE

### impl<T: Send> Payload for Base64<T>

#### const CONTENT_TYPE: &'static str = "text/plain; charset=utf-8"

### impl<T: Send> Payload for Binary<T>

#### const CONTENT_TYPE: &'static str = "application/octet-stream"

### impl<T: Send> Payload for Html<T>

#### const CONTENT_TYPE: &'static str = "text/html; charset=utf-8"

### impl<T: Send> Payload for PlainText<T>

#### const CONTENT_TYPE: &'static str = "text/plain; charset=utf-8"

### impl<T: Stream<Item = E> + Send + 'static, E: Type + ToJSON> Payload for EventStream<T>

#### const CONTENT_TYPE: &'static str = "text/event-stream"
```

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

### Get String Length

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Email.html

Returns the length of the string in bytes. Note that this is not the number of characters or graphemes.

```APIDOC
## pub fn len(&self) -> usize

### Description
Returns the length of `self` in bytes. This length might not correspond to the number of characters or graphemes a human perceives.

### Returns
- **usize**: The length of the string in bytes.

### Examples
```
let len = "foo".len();
assert_eq!(3, len);

assert_eq!("ƒoo".len(), 4); // fancy f!
assert_eq!("ƒoo".chars().count(), 3);
```
```

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

### SecurityScheme Derive Macro Usage

Source: https://docs.rs/poem-openapi/latest/poem_openapi/derive.SecurityScheme.html

Demonstrates the basic usage of the `SecurityScheme` derive macro with available attributes for configuration.

```APIDOC
## SecurityScheme

poem_openapi
# Derive Macro SecurityScheme Copy item path
Source
Search
Settings
Help
Summary
```rust
#[derive(SecurityScheme)]
{
    // Attributes available to this derive:
    #[oai]
}

```

Expand description
Define an OpenAPI Security Scheme.
## §Macro parameters
Attribute| Description| Type| Optional  
---|---|---|---  
rename| Rename the security scheme.| string| Y  
ty| The type of the security scheme. (api_key, basic, bearer, oauth2, openid_connect)| string| N  
key_in| `api_key` The location of the API key. Valid values are “query”, “header” or “cookie”. (query, header, cookie)| string| Y  
key_name| `api_key` The name of the header, query or cookie parameter to be used..| string| Y  
bearer_format| `bearer` A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.| string| Y  
flows| `oauth2` An object containing configuration information for the flow types supported.| OAuthFlows| Y  
openid_connect_url| OpenId Connect URL to discover OAuth2 configuration values.| string| Y  
checker| Specify a function to check the original authentication information and convert it to the return type of this function. This function must return `Option<T>` or `poem::Result<T>`, with `None` meaning a General Authorization error and an `Err` reflecting the error supplied.| string| Y  
## §OAuthFlows
Attribute| description| Type| Optional  
---|---|---|---  
implicit| Configuration for the OAuth Implicit flow| OAuthFlow| Y  
password| Configuration for the OAuth Resource Owner Password flow| OAuthFlow| Y  
client_credentials| Configuration for the OAuth Client Credentials flow| OAuthFlow| Y  
authorization_code| Configuration for the OAuth Authorization Code flow| OAuthFlow| Y  
## §OAuthFlow
Attribute| description| Type| Optional  
---|---|---|---  
authorization_url| `implicit` `authorization_code` The authorization URL to be used for this flow.| string| Y  
token_url| `password` `client_credentials` `authorization_code` The token URL to be used for this flow.| string| Y  
refresh_url| The URL to be used for obtaining refresh tokens.| string| Y  
scopes| The available scopes for the OAuth2 security scheme.| OAuthScopes| Y  
```

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

### Get ParseError Message

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.ParseError.html

Returns a reference to the error message associated with the `ParseError` without consuming it.

```rust
pub fn message(&self) -> &str
```

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

### Create OpenApiService

Source: https://docs.rs/poem-openapi/latest/poem_openapi/struct.OpenApiService.html

Constructor for OpenApiService. Initializes the OpenAPI container with the provided API, title, and version.

```rust
pub fn new(api: T, title: impl Into<String>, version: impl Into<String>) -> Self
```

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

### Create Redoc Endpoint

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/ui/redoc/mod.rs.html

Creates a Poem web server endpoint that serves the Redoc OpenAPI documentation UI at the root path ('/'). It takes the OpenAPI specification as a string, generates the HTML, and returns it as an HTML response.

```rust
use poem::{Endpoint, endpoint::make_sync, web::Html};

const REDOC_JS: &str = include_str!("redoc.standalone.js");

const REDOC_TEMPLATE: &str = r#"<!DOCTYPE html>
<html>
  <head>
    <title>Redoc</title>
    <!-- needed for adaptive design -->
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">

    <!--
    Redoc doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
    <script charset="UTF-8">{:script}</script>
  </head>
  <body>
    <div id="redoc-container"></div>
    
    <script>
        let spec = {:spec};
        Redoc.init(spec, {
          scrollYOffset: 50
        }, document.getElementById('redoc-container'));
    </script>
  </body>
</html>"#;

pub(crate) fn create_html(document: &str) -> String {
    REDOC_TEMPLATE
        .replace("{:script}", REDOC_JS)
        .replace("{:spec}", document)
}

pub(crate) fn create_endpoint(document: String) -> impl Endpoint {
    let ui_html = create_html(&document);
    poem::Route::new().at("/", make_sync(move |_| Html(ui_html.clone())))
}
```

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

### Example of as_mut_str()

Source: https://docs.rs/poem-openapi/latest/poem_openapi/types/struct.Email.html

Converts a String into a mutable string slice. This allows in-place modification of the string data.

```rust
let mut s = String::from("foobar");
let s_mut_str = s.as_mut_str();

s_mut_str.make_ascii_uppercase();

assert_eq!("FOOBAR", s_mut_str);
```

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

### Create Rapidoc Endpoint (with rapidoc feature)

Source: https://docs.rs/poem-openapi/latest/src/poem_openapi/openapi.rs.html

Generates an `Endpoint` that serves the RapiDoc UI. Requires the `rapidoc` feature.

```rust
pub fn rapidoc(&self) -> impl Endpoint + 'static
    where
        T: OpenApi,
        W: Webhook,
    {
        crate::ui::rapidoc::create_endpoint(self.spec())
    }
```
Tokens:
Raw