Crate poem_openapi

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.

Table of contents

• Features
• Quickstart
• Crate features

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.

Quickstart

Cargo.toml

[package]
name = "helloworld"
version = "0.1.0"
edition = "2021"

[dependencies]
poem = "3"
poem-openapi = { version = "5", features = ["swagger-ui"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

main.rs

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

struct Api;

#[OpenApi]
impl Api {
    /// Hello world
    #[oai(path = "/", method = "get")]
    async fn index(&self) -> PlainText<&'static str> {
        PlainText("Hello World")
    }
}

#[tokio::main]
async fn main() {
    let api_service =
        OpenApiService::new(Api, "Hello World", "1.0").server("http://localhost:3000");
    let ui = api_service.swagger_ui();
    let app = Route::new().nest("/", api_service).nest("/docs", ui);

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

Check it

Open your browser at http://127.0.0.1:3000.

You will see the plaintext response as:

Hello World

Interactive API docs

Now go to http://127.0.0.1:3000/docs.

You will see the automatic interactive API documentation (provided by Swagger UI):

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
scalar	Add Scalar UI support
stoplight-elements	Add Stoplight Elements UI support
email	Support for email address string
hostname	Support for hostname string
humantime	Integrate with the humantime crate
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

Modules

auth

Some certificate types for security scheme.

error

Some common error types.

macros

Macros to help with building custom payload types.

param

Parameter types for the API operation.

payload

Commonly used payload types.

types

Commonly used data types.

Macros

impl_apirequest_for_payload

This macro implements ApiExtractor for your type, with additional bounds if you want to.

Structs

ContactObject

A contact information for the exposed API.

ExternalDocumentObject

An object representing a external document.

ExtraHeader

An extra header

ExtractParamOptions

Options for the parameter extractor.

LicenseObject

A license information for the exposed API.

OpenApiService

An OpenAPI service for Poem.

OperationId

A operation id that can be obtained from the response

ServerObject

An object representing a Server.

Enums

ApiExtractorType

API extractor types.

ParameterStyle

The style of the passed parameter. See https://swagger.io/docs/specification/v3_0/serialization/ for details

Traits

ApiExtractor

Represents an OpenAPI extractor.

ApiResponse

Represents an OpenAPI responses object.

OAuthScopes

Represents a OAuth scopes.

OpenApi

Represents an OpenAPI object.

ResponseContent

Represents an OpenAPI response content object.

Tags

Represents an OpenAPI tags.

Validator

Represents a validator to validate the input value.

Webhook

Represents a webhook object.

Attribute Macros

OpenApi

Define an OpenAPI.

Webhook

Define an OpenAPI webhooks.

Derive Macros

ApiRequest

Define an OpenAPI request.

ApiResponse

Define an OpenAPI response.

Enum

Define an OpenAPI enum

Multipart

Define an OpenAPI payload.

NewType

Define a new type.

OAuthScopes

Define a OAuth scopes.

Object

Define an OpenAPI object

ResponseContent

Define an OpenAPI response content.

SecurityScheme

Define an OpenAPI Security Scheme.

Tags

Define an OpenAPI Tags.

Union

Define an OpenAPI discriminator object.