poem-openapi 5.1.16

OpenAPI support for Poem.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

Define an OpenAPI response.

# Macro parameters

| Attribute           | Description                                                                                     | Type                                                       | Optional |
|---------------------|-------------------------------------------------------------------------------------------------|------------------------------------------------------------|----------|
| bad_request_handler | Sets a custom bad request handler, it can convert error to the value of the this response type. | string                                                     | Y        |
| header              | Add an extra header                                                                             | [`ExtraHeader`](macro@ApiResponse#extra-header-parameters) | Y        |
| display             | When converting a response to an error, the error message comes from the `Display trait`.       | bool                                                       | Y        |

# Item parameters

| Attribute    | description                                                  | Type                                                       | Optional |
|--------------|--------------------------------------------------------------|------------------------------------------------------------|----------|
| status       | HTTP status code. If omitted, it is a default response type. | u16                                                        | Y        |
| status_range | Specify a range of HTTP status codes.                        | string                                                     | Y        |
| content_type | Specify the content type.                                    | string                                                     | Y        |
| actual_type  | Specifies the actual response type                           | string                                                     | Y        |
| header       | Add an extra header                                          | [`ExtraHeader`](macro@ApiResponse#extra-header-parameters) | Y        |

# Header parameters

| Attribute  | description       | Type   | Optional |
|------------|-------------------|--------|----------|
| deprecated | Header deprecated | String | Y        |

# Extra header parameters

| Attribute   | description        | Type   | Optional |
|-------------|--------------------|--------|----------|
| name        | Header name        | String | N        |
| ty          | Header type        | String | N        |
| description | Header description | String | Y        |
| deprecated  | Header deprecated  | bool   | Y        |

# Example response headers

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

#[derive(ApiResponse)]
enum CreateUserResponse {
    #[oai(status = 200)]
    Ok(#[oai(header = "X-Id")] String),
    #[oai(status = 201)]
    OkWithBody(PlainText<String>, #[oai(header = "X-Id")] String),
}
```

# Example extra headers

```rust
use poem_openapi::ApiResponse;

#[derive(ApiResponse)]
#[oai(
    header(name = "X-ExtraHeader-1", ty = "String"),
    header(name = "X-ExtraHeader-2", ty = "i32"),
)]
enum CreateUserResponse {
    #[oai(status = 200, header(name = "X-ExtraHeader-3", ty = "f32"))]
    Ok,
}
```

# Example status range

```rust
use poem::http::StatusCode;
use poem_openapi::{payload::PlainText, ApiResponse};

#[derive(ApiResponse)]
enum CreateUserResponse {
    #[oai(status_range = "2XX")]
    Ok(StatusCode, PlainText<String>),
    #[oai(status_range = "4XX")]
    ClientError(StatusCode),
    #[oai(status_range = "5XX")]
    ServerError(StatusCode),
}
```

# Example with bad request handler

```rust
use poem::Error;
use poem_openapi::{payload::PlainText, ApiResponse};

#[derive(ApiResponse)]
#[oai(bad_request_handler = "bad_request_handler")]
enum CreateUserResponse {
    /// Returns when the user is successfully created.
    #[oai(status = 200)]
    Ok,
    /// Returns when the user already exists.
    #[oai(status = 409)]
    UserAlreadyExists,
    /// Returns when the request parameters is incorrect.
    #[oai(status = 400)]
    BadRequest(PlainText<String>),
}

// Convert error to `CreateUserResponse::BadRequest`.
fn bad_request_handler(err: Error) -> CreateUserResponse {
    CreateUserResponse::BadRequest(PlainText(format!("error: {}", err.to_string())))
}
```

# Example as an error type

```rust
use poem::Error;
use poem_openapi::{payload::{PlainText, Json}, ApiResponse, Object, OpenApi};

#[derive(Object)]
struct CreateUserRequest {
    username: String,
    nickname: String,
    email: String,
}

#[derive(ApiResponse)]
enum CreateUserResponse {
    /// Returns when the user is successfully created.
    #[oai(status = 200)]
    Ok,
}

#[derive(ApiResponse)]
enum CreateUserResponseError {
    /// Returns when the user already exists.
    #[oai(status = 409)]
    UserAlreadyExists,
    /// Returns when the request parameters is incorrect.
    #[oai(status = 400)]
    BadRequest(PlainText<String>),
}

struct UserApi;

#[OpenApi]
impl UserApi {
    /// Create a new user.
    #[oai(path = "/user", method = "post")]
    async fn create(
        &self,
        user: Json<CreateUserRequest>,
    ) -> Result<CreateUserResponse, CreateUserResponseError> {
        todo!()
    }
}
```