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
- Define a OpenAPI.
- Define a OpenApi webhooks.
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.