170 stable releases
new 5.1.3 | Nov 20, 2024 |
---|---|
5.1.1 | Sep 13, 2024 |
5.0.3 | Jul 19, 2024 |
5.0.0 | Mar 30, 2024 |
0.9.0 | Oct 8, 2021 |
#119 in Asynchronous
51,327 downloads per month
Used in 122 crates
(38 directly)
5MB
32K
SLoC
Poem OpenAPI
Fast and Type-Safe OpenAPI implementation for Poem.
Poem-openapi
allows you to easily implement APIs that comply with the OpenAPIv3
specification.
It uses procedural macros to generate a lots of boilerplate code, so that you only need to focus on the more
important business implementations.
Features
- Type safety If your codes can be compiled, then it is fully compliant with the
OpenAPI v3
specification. - Rustfmt friendly Do not create any DSL that does not conform to Rust's syntax specifications.
- IDE friendly Any code generated by the procedural macro will not be used directly.
- Minimal overhead All generated code is necessary, and there is almost no overhead.
Crate features
To avoid compiling unused dependencies, Poem gates certain features, some of which are disabled by default:
Feature | Description |
---|---|
chrono | Integrate with the chrono crate. |
time | Integrate with the time crate. |
humantime | Integrate with the humantime crate |
openapi-explorer | Add OpenAPI Explorer support |
swagger-ui | Add swagger UI support |
rapidoc | Add RapiDoc UI support |
redoc | Add Redoc UI support |
Support for email address string | |
hostname | Support for hostname string |
uuid | Integrate with the uuid crate |
url | Integrate with the url crate |
geo | Integrate with the geo-types crate |
bson | Integrate with the bson crate |
rust_decimal | Integrate with the rust_decimal crate |
prost-wkt-types | Integrate with the prost-wkt-types crate |
static-files | Support for static file response |
websocket | Support for websocket |
sonic-rs | Uses sonic-rs instead of serde_json . Pls, checkout sonic-rs requirements to properly enable sonic-rs capabilities |
Safety
This crate uses #![forbid(unsafe_code)]
to ensure everything is implemented in 100% Safe Rust.
Example
use poem::{listener::TcpListener, Route};
use poem_openapi::{param::Query, payload::PlainText, OpenApi, OpenApiService};
struct Api;
#[OpenApi]
impl Api {
#[oai(path = "/hello", method = "get")]
async fn index(&self, name: Query<Option<String>>) -> PlainText<String> {
match name.0 {
Some(name) => PlainText(format!("hello, {}!", name)),
None => PlainText("hello!".to_string()),
}
}
}
#[tokio::main]
async fn main() -> Result<(), std::io::Error> {
let api_service =
OpenApiService::new(Api, "Hello World", "1.0").server("http://localhost:3000/api");
let ui = api_service.swagger_ui();
let app = Route::new().nest("/api", api_service).nest("/", ui);
poem::Server::new(TcpListener::bind("0.0.0.0:3000"))
.run(app)
.await
}
This feature needs to be opted-in. It can be done by adding the feature in Cargo.toml
file
[dependencies]
poem = "3"
poem-openapi = { version = "5", features = ["swagger-ui"]}
tokio = { version = "1", features = ["full"] }
Run example
Open http://localhost:3000/
in your browser, you will see the Swagger UI
that contains these API definitions.
> cargo run --example hello_world
> curl http://localhost:3000/api/hello
hello!
> curl http://localhost:3000/api/hello?name=sunli
hello, sunli!
MSRV
The minimum supported Rust version for this crate is 1.81.0
.
Contributing
🎈 Thanks for your help improving the project! We are so happy to have you!
License
Licensed under either of
- Apache License, Version 2.0,(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Poem by you, shall be licensed as Apache, without any additional terms or conditions.
Dependencies
~23–42MB
~756K SLoC