armature_openapi/lib.rs
1//! OpenAPI 3.0 specification generation and Swagger UI integration for Armature
2//!
3//! This crate provides tools for generating OpenAPI specifications and serving
4//! interactive API documentation via Swagger UI.
5//!
6//! ## Features
7//!
8//! - 📝 **Programmatic API** - Build OpenAPI specs with fluent builder
9//! - 📊 **Swagger UI** - Interactive API documentation
10//! - 📤 **JSON/YAML Export** - Multiple export formats
11//! - 🔒 **Type-Safe** - Strongly typed OpenAPI 3.0 specification
12//! - 🔐 **Auth Schemes** - Bearer, API Key, OAuth2, OpenID
13//! - 📋 **Schema Support** - Request/response schemas
14//!
15//! ## Quick Start - Basic API Spec
16//!
17//! ```
18//! use armature_openapi::OpenApiBuilder;
19//!
20//! let spec = OpenApiBuilder::new("My API", "1.0.0")
21//! .description("A wonderful API")
22//! .server("http://localhost:3000", None)
23//! .build();
24//!
25//! assert_eq!(spec.info.title, "My API");
26//! assert_eq!(spec.info.version, "1.0.0");
27//! assert_eq!(spec.servers.len(), 1);
28//! ```
29//!
30//! ## Adding Authentication
31//!
32//! ```
33//! use armature_openapi::{OpenApiBuilder, ApiKeyLocation};
34//!
35//! let spec = OpenApiBuilder::new("Secure API", "1.0.0")
36//! .add_bearer_auth("bearer")
37//! .add_api_key_auth("api_key", "X-API-Key", ApiKeyLocation::Header)
38//! .build();
39//!
40//! assert!(spec.components.is_some());
41//! let components = spec.components.unwrap();
42//! assert!(components.security_schemes.contains_key("bearer"));
43//! assert!(components.security_schemes.contains_key("api_key"));
44//! ```
45//!
46//! ## Adding Paths and Operations
47//!
48//! ```
49//! use armature_openapi::{OpenApiBuilder, PathItem, Operation, Response};
50//! use std::collections::HashMap;
51//!
52//! let mut get_operation = Operation::default();
53//! get_operation.summary = Some("Get user by ID".to_string());
54//! get_operation.operation_id = Some("getUserById".to_string());
55//!
56//! let mut responses = HashMap::new();
57//! responses.insert("200".to_string(), Response {
58//! description: "Successful response".to_string(),
59//! content: None,
60//! });
61//! get_operation.responses = responses;
62//!
63//! let mut path_item = PathItem::default();
64//! path_item.get = Some(get_operation);
65//!
66//! let mut spec = OpenApiBuilder::new("User API", "1.0.0").build();
67//! spec.paths.insert("/users/{id}".to_string(), path_item);
68//!
69//! assert!(spec.paths.contains_key("/users/{id}"));
70//! assert!(spec.paths.get("/users/{id}").unwrap().get.is_some());
71//! ```
72//!
73//! ## Swagger UI Configuration
74//!
75//! ```
76//! use armature_openapi::{OpenApiBuilder, SwaggerConfig};
77//!
78//! let spec = OpenApiBuilder::new("My API", "1.0.0")
79//! .description("API with Swagger UI")
80//! .build();
81//!
82//! let swagger_config = SwaggerConfig::new("/api-docs", spec)
83//! .with_title("My API Documentation");
84//!
85//! // Configuration ready
86//! assert_eq!(swagger_config.path, "/api-docs");
87//! assert_eq!(swagger_config.title, "My API Documentation");
88//! ```
89//!
90//! ## Adding Multiple Servers
91//!
92//! ```
93//! use armature_openapi::OpenApiBuilder;
94//!
95//! let spec = OpenApiBuilder::new("Multi-Env API", "1.0.0")
96//! .server("https://api.production.com", Some("Production server".to_string()))
97//! .server("https://api.staging.com", Some("Staging server".to_string()))
98//! .server("http://localhost:3000", Some("Local development".to_string()));
99//!
100//! let built_spec = spec.build();
101//!
102//! assert_eq!(built_spec.servers.len(), 3);
103//! assert_eq!(built_spec.servers[0].url, "https://api.production.com");
104//! assert_eq!(built_spec.servers[1].url, "https://api.staging.com");
105//! assert_eq!(built_spec.servers[2].url, "http://localhost:3000");
106//! assert_eq!(built_spec.servers[0].description, Some("Production server".to_string()));
107//! ```
108
109pub mod builder;
110pub mod playground;
111pub mod spec;
112pub mod swagger;
113
114pub use builder::*;
115pub use playground::*;
116pub use spec::*;
117pub use swagger::*;