Poem Web Framework

Poem is a full-featured and easy-to-use web framework for the Rust programming language. The ecosystem consists of several specialized crates depending on your deployment and protocol needs:

• poem: The core Poem Web framework.
• poem-lambda: Support for running Poem on AWS Lambda.
• poem-openapi: OpenAPI specification support for Poem Web.
• poem-grpc: gRPC support for Poem.
• poem-mcpserver: Model Context Protocol (MCP) Server implementation for Poem.

You can find practical implementations and usage patterns in the official examples directory on GitHub.

https://github.com/poem-web/poem/tree/master/examples

Use the #[derive(Tags)] macro on an enum to define OpenAPI tags for your API. Each variant in the enum represents a tag. You can use doc comments on the enum variants to provide descriptions for the tags in the generated OpenAPI specification.

use poem_openapi::Tags;

#[derive(Tags)]
enum ApiTags {
    /// Operations about user
    User,
    /// Operations about pet
    Pet,
}

You can provide a custom handler to the ApiResponse macro to intercept errors and convert them into a specific response variant. This is useful for mapping internal poem::Error types to your API's error responses.

1. Define the handler function: fn handler(err: Error) -> YourResponseEnum.
2. Reference the function name in the macro: #[oai(bad_request_handler = "handler_name")].

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

#[derive(ApiResponse)]
#[oai(bad_request_handler = "bad_request_handler")]
enum CreateUserResponse {
    #[oai(status = 200)]
    Ok,
    #[oai(status = 409)]
    UserAlreadyExists,
    #[oai(status = 400)]
    BadRequest(PlainText<String>),
}

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

Use the #[derive(OAuthScopes)] macro on an enum to define a set of OAuth scopes for your API. This allows the OpenAPI specification to correctly represent the available scopes for OAuth2 authentication.

use poem_openapi::OAuthScopes;

#[derive(OAuthScopes)]
enum GithubScopes {
    /// Read data
    Read,
    /// Write data
    Write,
}

To define multiple possible content types for an OpenAPI response, implement the ResponseContent derive macro on an enum. Each variant of the enum represents a different content type (e.g., Json, PlainText, Binary).

use poem_openapi::{
    payload::{Binary, Json, PlainText},
    ApiResponse, ResponseContent,
};

#[derive(ResponseContent)]
enum MyResponseContent {
    A(Json<i32>),
    B(PlainText<String>),
    C(Binary<Vec<u8>>),
}

#[derive(ApiResponse)]
enum MyResponse {
    #[oai(status = 200)]
    Ok(MyResponseContent),
}

You can define OpenAPI webhooks by implementing a trait decorated with the #[Webhook] macro. The OpenApiService can then include these webhooks using the .webhooks::<T>() method, where T is a trait object of your webhook definition.

Webhooks are defined via Rust documentation comments for summary and description, and via the #[oai(...)] attribute for operation-specific metadata.

use poem_openapi::{Object, Webhook, payload::Json, OpenApiService};

#[derive(Object)]
struct Pet {
    id: i64,
    name: String,
}

#[Webhook]
trait MyWebhooks {
    /// This is the summary of the operation
    ///
    /// This is the description of the operation
    #[oai(method = "post")]
    fn new_pet(&self, pet: Json<Pet>);
}

let api = OpenApiService::new((), "Demo", "1.0.0")
    .webhooks::<&dyn MyWebhooks>();

When using the #[derive(Union)] macro, you can define an OpenAPI discriminator to help clients identify which variant of a union is being sent in a payload. This is done using the #[oai(discriminator_name = "...")] attribute on the enum.

To use a discriminator, specify the property name that will hold the type identifier using discriminator_name.

use poem_openapi::{Object, Union};

#[derive(Object, Debug, PartialEq)]
struct A {
    v1: i32,
    v2: String,
}

#[derive(Object, Debug, PartialEq)]
struct B {
    v3: f32,
}

#[derive(Union, Debug, PartialEq)]
#[oai(discriminator_name = "type")]
enum MyObj {
    A(A),
    B(B),
}

Use the #[derive(NewType)] macro to wrap an existing type into a new type that automatically implements the necessary OpenAPI traits for JSON serialization, parameter parsing, and header conversion. By default, it implements ParseFromJSON, ParseFromParameter, ParseFromMultipartField, ToJSON, and ToHeader.

use poem_openapi::NewType;

#[derive(NewType)]
struct MyString(String);

Use the #[derive(Enum)] macro from poem_openapi to define an enum that will be represented in your OpenAPI schema. You can customize the enum's name, its casing convention, and its deprecation status using macro attributes.

use poem_openapi::Enum;

#[derive(Enum)]
enum PetStatus {
    Available,
    Pending,
    Sold,
}

Use the #[derive(ApiResponse)] macro on an enum to define the possible OpenAPI responses for an API endpoint. You can specify HTTP status codes, content types, and headers using the #[oai(...)] attribute on individual enum variants.

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),
}