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.

• Docs
• Cargo package

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 | | email | Support for email address string | | hostname | Support for hostname string | | uuid | Integrate with the uuid crate | | url | Integrate with the url crate | | bson | Integrate with the bson crate | | rust_decimal | Integrate with the rust_decimal crate | | static-files | Support for static file response | | websocket | Support for websocket |

Safety

This crate uses #![forbid(unsafe_code)] to ensure everything is implemented in 100% Safe Rust.

Example

```rust 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>) -> PlainText { match name.0 { Some(name) => PlainText(format!("hello, {}!", name)), None => PlainText("hello!".to_string()), } } }

[tokio::main]

async fn main() -> Result<(), std::io::Error> { let apiservice = OpenApiService::new(Api, "Hello World", "1.0").server("http://localhost:3000/api"); let ui = apiservice.swaggerui(); let app = Route::new().nest("/api", apiservice).nest("/", ui);

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

} ```

This feature needs to be opted-in. It can be done by adding the feature in Cargo.toml file toml filename=Cargo.toml [dependencies] poem = "1" poem-openapi = { version = "2", 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.

```shell

cargo run --example hello_world

curl http://localhost:3000 hello!

curl http://localhost:3000\?name\=sunli hello, sunli!
```

MSRV

The minimum supported Rust version for this crate is 1.64.0.

Contributing

:balloon: 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.