silent_openapi/
lib.rs

1//! # Silent OpenAPI
2//!
3//! 为Silent Web框架提供OpenAPI 3.0支持，包括自动文档生成和Swagger UI集成。
4//!
5//! ## 主要特性
6//!
7//! - 🚀 基于utoipa的高性能OpenAPI文档生成
8//! - 📖 内置Swagger UI界面
9//! - 🔧 与Silent框架深度集成
10//! - 📝 支持路由文档自动收集
11//! - 🎯 零运行时开销的编译时文档生成
12//!
13//! ## 快速开始
14//!
15//! ```ignore
16//! use silent::prelude::*;
17//! use silent_openapi::{OpenApiDoc, SwaggerUiHandler};
18//! use utoipa::OpenApi;
19//!
20//! #[derive(OpenApi)]
21//! #[openapi(
22//!     paths(get_hello),
23//!     components(schemas())
24//! )]
25//! struct ApiDoc;
26//!
27//! async fn get_hello(_req: Request) -> Result<Response> {
28//!     Ok(Response::text("Hello, OpenAPI!"))
29//! }
30//!
31//! fn main() {
32//!     let route = Route::new("")
33//!         .get(get_hello)
34//!         .append(SwaggerUiHandler::new("/swagger-ui", ApiDoc::openapi()));
35//!
36//!     Server::new().run(route);
37//! }
38//! ```
39
40pub mod doc;
41#[cfg(feature = "swagger-ui-embedded")]
42pub mod embedded;
43pub use silent_openapi_macros::endpoint;
44pub mod error;
45pub mod handler;
46pub mod middleware;
47pub mod redoc;
48pub mod route;
49pub mod schema;
50pub mod ui_html;
51
52// 重新导出核心类型
53pub use error::{OpenApiError, Result};
54pub use handler::SwaggerUiHandler;
55pub use middleware::SwaggerUiMiddleware;
56pub use redoc::{ReDocHandler, ReDocMiddleware};
57pub use route::{DocumentedRoute, RouteDocumentation, RouteOpenApiExt};
58pub use schema::OpenApiDoc;
59
60// 重新导出utoipa的核心类型，方便用户使用
61pub use utoipa::{
62    IntoParams, IntoResponses, ToResponse, ToSchema,
63    openapi::{self, OpenApi},
64};
65
66/// Silent OpenAPI的版本信息
67pub const VERSION: &str = env!("CARGO_PKG_VERSION");
68
69/// Swagger UI 配置选项
70#[derive(Clone)]
71pub struct SwaggerUiOptions {
72    pub try_it_out_enabled: bool,
73}
74
75impl Default for SwaggerUiOptions {
76    fn default() -> Self {
77        Self {
78            try_it_out_enabled: true,
79        }
80    }
81}
82
83/// 创建一个基础的OpenAPI文档结构
84///
85/// # 参数
86///
87/// - `title`: API标题
88/// - `version`: API版本
89/// - `description`: API描述
90///
91/// # 示例
92///
93/// ```rust
94/// use silent_openapi::create_openapi_doc;
95///
96/// let openapi = create_openapi_doc(
97///     "用户管理API",
98///     "1.0.0",
99///     "基于Silent框架的用户管理系统"
100/// );
101/// ```
102pub fn create_openapi_doc(
103    title: &str,
104    version: &str,
105    description: &str,
106) -> utoipa::openapi::OpenApi {
107    use utoipa::openapi::*;
108
109    OpenApiBuilder::new()
110        .info(
111            InfoBuilder::new()
112                .title(title)
113                .version(version)
114                .description(Some(description))
115                .build(),
116        )
117        .build()
118}
119
120#[cfg(test)]
121mod tests {
122    use super::*;
123
124    #[test]
125    fn test_version() {
126        #[allow(clippy::const_is_empty)]
127        {
128            assert!(!VERSION.is_empty());
129        }
130    }
131
132    #[test]
133    fn test_create_openapi_doc() {
134        let doc = create_openapi_doc("Test API", "1.0.0", "A test API");
135        assert_eq!(doc.info.title, "Test API");
136        assert_eq!(doc.info.version, "1.0.0");
137        assert_eq!(doc.info.description, Some("A test API".to_string()));
138    }
139}
silent_openapi/lib.rs

silent_openapi/
lib.rs
