docs(openapi): provide usage examples for status_range

poem-web · Feb 12, 2025 · f2638f5 · f2638f5
1 parent f09290d
commit f2638f5
Showing 1 changed file with 18 additions and 0 deletions.
diff --git a/poem-openapi/src/docs/response.md b/poem-openapi/src/docs/response.md
@@ -13,6 +13,7 @@ Define an OpenAPI response.
 | 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        |
@@ -62,6 +63,23 @@ enum CreateUserResponse {
 }
 ```
 
+# 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