tako/
openapi.rs

1//! OpenAPI documentation generation integrations.
2//!
3//! This module provides integrations with popular OpenAPI documentation generators:
4//!
5//! - **utoipa**: Compile-time OpenAPI documentation generation via derive macros.
6//!   Enable with the `utoipa` feature.
7//!
8//! - **vespera**: OpenAPI 3.1 specification structures and route discovery.
9//!   Enable with the `vespera` feature.
10//!
11//! # Route-Level Integration
12//!
13//! Both integrations support route-level OpenAPI metadata:
14//!
15//! ```rust,ignore
16//! use tako::{router::Router, Method};
17//!
18//! let mut router = Router::new();
19//! router.route(Method::GET, "/users/{id}", get_user)
20//!     .summary("Get user by ID")
21//!     .description("Retrieves a user by their unique identifier")
22//!     .tag("users")
23//!     .response(200, "Successful response")
24//!     .response(404, "User not found");
25//! ```
26//!
27//! # Examples
28//!
29//! ## Using utoipa
30//!
31//! ```rust,ignore
32//! use tako::openapi::utoipa::{OpenApi, OpenApiJson, ToSchema};
33//!
34//! #[derive(ToSchema)]
35//! struct User {
36//!     id: u64,
37//!     name: String,
38//! }
39//!
40//! #[derive(OpenApi)]
41//! #[openapi(components(schemas(User)))]
42//! struct ApiDoc;
43//!
44//! async fn openapi(_req: tako::types::Request) -> OpenApiJson {
45//!     OpenApiJson(ApiDoc::openapi())
46//! }
47//! ```
48//!
49//! ## Using vespera
50//!
51//! ```rust,ignore
52//! use tako::openapi::vespera::{OpenApi, Info, VesperaOpenApiJson};
53//!
54//! async fn openapi(_req: tako::types::Request) -> VesperaOpenApiJson {
55//!     let spec = OpenApi {
56//!         info: Info {
57//!             title: "My API".to_string(),
58//!             version: "1.0.0".to_string(),
59//!             ..Default::default()
60//!         },
61//!         ..Default::default()
62//!     };
63//!     VesperaOpenApiJson(spec)
64//! }
65//! ```
66
67use std::collections::BTreeMap;
68
69/// OpenAPI metadata that can be attached to a route.
70///
71/// This struct stores operation-level OpenAPI information that can be
72/// used to generate OpenAPI specifications from Tako routes.
73#[derive(Clone, Debug, Default)]
74pub struct RouteOpenApi {
75    /// Unique identifier for the operation.
76    pub operation_id: Option<String>,
77    /// Short summary of the operation.
78    pub summary: Option<String>,
79    /// Detailed description of the operation.
80    pub description: Option<String>,
81    /// Tags for grouping operations.
82    pub tags: Vec<String>,
83    /// Whether the operation is deprecated.
84    pub deprecated: bool,
85    /// Response descriptions keyed by status code.
86    pub responses: BTreeMap<u16, String>,
87    /// Parameter descriptions.
88    pub parameters: Vec<OpenApiParameter>,
89    /// Request body description.
90    pub request_body: Option<OpenApiRequestBody>,
91    /// Security requirements.
92    pub security: Vec<String>,
93}
94
95/// OpenAPI parameter definition.
96#[derive(Clone, Debug)]
97pub struct OpenApiParameter {
98    /// Parameter name.
99    pub name: String,
100    /// Parameter location (query, header, path, cookie).
101    pub location: ParameterLocation,
102    /// Parameter description.
103    pub description: Option<String>,
104    /// Whether the parameter is required.
105    pub required: bool,
106}
107
108/// Location of an OpenAPI parameter.
109#[derive(Clone, Debug, Default)]
110pub enum ParameterLocation {
111    #[default]
112    Query,
113    Header,
114    Path,
115    Cookie,
116}
117
118/// OpenAPI request body definition.
119#[derive(Clone, Debug)]
120pub struct OpenApiRequestBody {
121    /// Description of the request body.
122    pub description: Option<String>,
123    /// Whether the request body is required.
124    pub required: bool,
125    /// Content type (e.g., "application/json").
126    pub content_type: String,
127    /// Schema properties for the request body (name, type, description).
128    pub schema_properties: Vec<RequestBodyProperty>,
129}
130
131/// A property definition for request body schema.
132#[derive(Clone, Debug)]
133pub struct RequestBodyProperty {
134    /// Property name.
135    pub name: String,
136    /// Property type (e.g., "string", "integer", "boolean").
137    pub property_type: String,
138    /// Property description.
139    pub description: Option<String>,
140}
141
142#[cfg(feature = "utoipa")]
143#[cfg_attr(docsrs, doc(cfg(feature = "utoipa")))]
144pub mod utoipa;
145
146#[cfg(feature = "vespera")]
147#[cfg_attr(docsrs, doc(cfg(feature = "vespera")))]
148pub mod vespera;
149
150/// OpenAPI UI helpers (Swagger UI, Scalar, RapiDoc, Redoc).
151pub mod ui;
tako/openapi.rs

tako/
openapi.rs
