Crate poem_openapi[][src]

Expand description

OpenAPI support 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.


  • 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:

FeatureDescriptionDefault enabled
chronoIntegrate with the chrono crate.:x:
swagger-uiAdd swagger UI support:heavy_check_mark:


use poem::{listener::TcpListener, Route};
use poem_openapi::{payload::PlainText, OpenApi, OpenApiService};

struct Api;

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

async fn main() -> Result<(), std::io::Error> {
    let listener = TcpListener::bind("");
    let api_service = OpenApiService::new(Api)
        .title("Hello World")
    let ui = api_service.swagger_ui();

        .run(Route::new().nest("/api", api_service).nest("/", ui))

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

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


Some certificate types for security scheme.

Commonly used payload types.

Commonly used data types.


API for the combine method.

An OpenAPI service for Poem.


This type represents errors that occur when parsing the HTTP request.


Represents a OpenAPI request object.

Represents a OpenAPI responses object.

Represents a OAuth scopes.

Represents a OpenAPI object.

Represents a OpenAPI security scheme.

Represents a OpenAPI tags.

Attribute Macros

Define a OpenAPI.

Derive Macros

Define a OpenAPI request.

Define a OpenAPI response.

Define a OpenAPI enum

Define a OpenAPI payload.

Define a OAuth scopes.

Define a OpenAPI object

Define a OpenAPI discriminator object.

Define a OpenAPI Security Scheme.

Define a OpenAPI Tags.