Crate poem_openapi
source ·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.
Table of contents
Features
- Type safety If your codes can be compiled, then it is fully compliant
with the
OpenAPI v3specification. - 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 = "1.2"
poem-openapi = { version = "1.2", 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")
}
}
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 |
| swagger-ui | Add swagger UI support |
| rapidoc | Add RapiDoc UI support |
| redoc | Add Redoc UI support |
| Support for email address string | |
| hostname | Support for hostname string |
| uuid | Integrate with the uuid crate |
| url | Integrate with the url crate |
| bson | Integrate with the bson crate |
| rust_decimal | Integrate with the rust_decimal crate |
| static-files | Support for static file response |
Modules
Some certificate types for security scheme.
Some common error types.
Macros to help with building custom payload types.
Parameter types for the API operation.
Commonly used payload types.
Commonly used data types.
Macros
This macro implements ApiExtractor for your type, with additional bounds
if you want to.
Structs
A contact information for the exposed API.
An object representing a external document.
An extra header
Options for the parameter extractor.
A license information for the exposed API.
An OpenAPI service for Poem.
A operation id that can be obtained from the response
An object representing a Server.
Enums
API extractor types.
Traits
Represents a OpenAPI extractor.
Represents a OpenAPI responses object.
Represents a OAuth scopes.
Represents a OpenAPI object.
Represents a OpenAPI response content object.
Represents a OpenAPI tags.
Represents a validator for validate the input value.
Represents a webhook object.
Attribute Macros
Derive Macros
Define a OpenAPI request.
Define a OpenAPI response.
Define a OpenAPI enum
Define a OpenAPI payload.
Define a new type.
Define a OAuth scopes.
Define a OpenAPI object
Define a OpenAPI response content.
Define a OpenAPI Security Scheme.
Define a OpenAPI Tags.
Define a OpenAPI discriminator object.