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.

• Book
• 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.
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

Example

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

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

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

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!

Modules

auth

Some certificate types for security scheme.

param

Parameter types for the API operation.

payload

Commonly used payload types.

types

Commonly used data types.

Structs

CombinedAPI

API for the combine method.

ExtractParamOptions

Options for the parameter extractor.

LicenseObject

A license information for the exposed API.

OpenApiService

An OpenAPI service for Poem.

ServerObject

An object representing a Server.

Enums

ApiExtractorType

API extractor types.

ParseRequestError

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

Traits

ApiExtractor

Represents a OpenAPI extractor.

ApiResponse

Represents a OpenAPI responses object.

OAuthScopes

Represents a OAuth scopes.

OpenApi

Represents a OpenAPI object.

Tags

Represents a OpenAPI tags.

Attribute Macros

OpenApi

Define a OpenAPI.

Derive Macros

ApiRequest

Define a OpenAPI request.

ApiResponse

Define a OpenAPI response.

Enum

Define a OpenAPI enum

Multipart

Define a OpenAPI payload.

OAuthScopes

Define a OAuth scopes.

Object

Define a OpenAPI object

OneOf

Define a OpenAPI discriminator object.

SecurityScheme

Define a OpenAPI Security Scheme.

Tags

Define a OpenAPI Tags.