1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

//! 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](https://poem-web.github.io/poem/)
//! * [Docs](https://docs.rs/poem-openapi)
//! * [Cargo package](https://crates.io/crates/poem-openapi)
//!
//! ## 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, all of
//! which are disabled by default:
//!
//! |Feature           |Description                     |
//! |------------------|--------------------------------|
//! |chrono            | Integrate with the [`chrono` crate](https://crates.io/crates/chrono).          |
//!
//! ## Example
//!
//! ```no_run
//! use poem::{listener::TcpListener, route};
//! use poem_openapi::{payload::PlainText, OpenApi, OpenApiService};
//!
//! struct Api;
//!
//! #[OpenApi]
//! impl Api {
//!     #[oai(path = "/hello", method = "get")]
//!     async fn index(
//!         &self,
//!         #[oai(name = "name", in = "query")] name: Option<String>,
//!     ) -> PlainText<String> {
//!         match name {
//!             Some(name) => PlainText(format!("hello, {}!", name)),
//!             None => PlainText("hello!".to_string()),
//!         }
//!     }
//! }
//!
//! #[tokio::main]
//! async fn main() -> Result<(), std::io::Error> {
//!     let listener = TcpListener::bind("127.0.0.1:3000");
//!     let api_service = OpenApiService::new(Api)
//!         .title("Hello World")
//!         .server("http://localhost:3000/api");
//!     let ui = api_service.swagger_ui("http://localhost:3000");
//!
//!     poem::Server::new(listener)
//!         .await?
//!         .run(route().nest("/api", api_service).nest("/", ui))
//!         .await
//! }
//! ```
//!
//! ## Run example
//!
//! Open `http://localhost:3000/ui` in your browser, you will see the `Swagger UI` that contains these API definitions.
//!
//! ```shell
//! > cargo run --example hello_world
//!
//! > curl http://localhost:3000
//! hello!
//!
//! > curl http://localhost:3000\?name\=sunli
//! hello, sunli!
//! ```

#![forbid(unsafe_code)]
#![deny(private_in_public, unreachable_pub)]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![warn(missing_docs)]

pub mod auth;
mod base;
mod error;
mod openapi;
#[doc(hidden)]
pub mod param;
pub mod payload;
#[doc(hidden)]
pub mod registry;
pub mod types;
#[doc(hidden)]
pub mod ui;
#[doc(hidden)]
pub mod validation;

pub use base::{ApiRequest, ApiResponse, CombinedAPI, OAuthScopes, OpenApi, SecurityScheme, Tags};
pub use error::ParseRequestError;
pub use openapi::OpenApiService;
#[doc(hidden)]
pub use poem;
#[doc = include_str!("docs/request.md")]
pub use poem_openapi_derive::ApiRequest;
#[doc = include_str!("docs/response.md")]
pub use poem_openapi_derive::ApiResponse;
#[doc = include_str!("docs/enum.md")]
pub use poem_openapi_derive::Enum;
#[doc = include_str!("docs/multipart.md")]
pub use poem_openapi_derive::Multipart;
#[doc = include_str!("docs/oauth_scopes.md")]
pub use poem_openapi_derive::OAuthScopes;
#[doc = include_str!("docs/object.md")]
pub use poem_openapi_derive::Object;
#[doc = include_str!("docs/openapi.md")]
pub use poem_openapi_derive::OpenApi;
#[doc = include_str!("docs/security_scheme.md")]
pub use poem_openapi_derive::SecurityScheme;
#[doc = include_str!("docs/tags.md")]
pub use poem_openapi_derive::Tags;
#[doc(hidden)]
pub use serde;
#[doc(hidden)]
pub use serde_json;