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

• Fully supports async/await
• Type safety
• Rustfmt friendly (Procedural Macro)
• Minimal overhead

Crate features

To avoid compiling unused dependencies, Poem gates certain features, all of which are disabled by default:

Example

use poem::listener::TcpListener;
use poem_openapi::{payload::PlainText, OpenAPI, API};

struct Api;

#[API]
impl Api {
    #[oai(path = "/", method = "get")]
    async fn index(&self, #[oai(name = "name", in = "query")] name: Option<String>) -> PlainText {
        match name {
            Some(name) => format!("hello, {}!", name).into(),
            None => "hello!".into(),
        }
    }
}

#[tokio::main]
async fn main() {
    let listener = TcpListener::bind("127.0.0.1:3000");
    poem::Server::new(listener)
        .await
        .unwrap()
        .run(OpenAPI::new(Api).title("hello World").ui_path("/ui"))
        .await
        .unwrap();
}

Run example

Open http://localhost:3000/ui in your browser, you will see the Swagger UI that contains these API definitions.

> cargo run --example hello_world

> curl http://localhost:3000
hello!

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