oas 0.2.1

OpenAPi Specification
Documentation 
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

//! # OpenAPI Specification (OAS) 3.0 Rust Implementation
//!
//! This crate provides a complete implementation of the OpenAPI Specification 3.0 in Rust,
//! with comprehensive support for serialization/deserialization and convenient builder patterns
//! for programmatic API specification creation.
//!
//! ## Features
//!
//! - **Complete OAS 3.0 Support**: All OpenAPI 3.0 specification features including schemas,
//!   operations, parameters, responses, security, callbacks, and links
//! - **Serde Integration**: Full JSON/YAML serialization and deserialization support
//! - **Builder Patterns**: Fluent APIs for easy specification construction
//! - **Type Safety**: Leverages Rust's type system to prevent invalid specifications
//! - **Reference System**: Support for both inline definitions and `$ref` references
//!
//! ## Quick Start
//!
//! ```rust
//! use oas::{builders, Referenceable, PathItem, Tag, Server};
//!
//! let api = builders::api("My API", "1.0.0")
//!     .with_description("A sample API")
//!     .add_server(Server::new("https://api.example.com"))
//!     .add_path("/users", PathItem::new()
//!         .with_get(builders::get("List users")
//!             .response("200", Referenceable::ok("User list"))
//!             .build()));
//!
//! println!("{}", api.to_string());
//! ```
//!
//! ## Core Types
//!
//! - [`OpenAPIV3`] - The root OpenAPI document
//! - [`Referenceable<T>`] - Wrapper for inline data or references
//! - [`builders`] - Module containing builder utilities
//! - [`OperationBuilder`] - Builder for complex operations
//!
//! ## Reference vs Inline Data
//!
//! The [`Referenceable<T>`] type allows you to specify either inline data or references
//! to reusable components:
//!
//! ```rust
//! use oas::{Referenceable, Schema};
//!
//! // Inline schema
//! let inline = Referenceable::data(Schema::string());
//!
//! // Reference to component
//! let reference = Referenceable::schema_ref("User");
//! ```

// Module declarations
pub mod builders;
pub mod extensions;
pub mod security;
pub mod types;

// Re-export main types for convenience
pub use security::*;
pub use types::*;

// Re-export builder functionality
pub use builders::*;

#[cfg(test)]
mod test {
    mod pass {
        use crate::OpenAPIV3;
        use assert_json_diff::assert_json_eq;

        macro_rules! pass {
            ($t:ty, $value:expr) => {
                serde_json::from_str::<$t>($value).unwrap();
                let new =
                    serde_json::to_value(&serde_json::from_str::<$t>($value).unwrap()).unwrap();
                let original = serde_json::from_str::<serde_json::Value>($value).unwrap();
                assert_json_eq!(dbg!(new), original);
            };
        }

        #[test]
        fn should_should_pass() {
            pass! { OpenAPIV3, include_str!("../openapi3-examples/3.0/pass/swagger2openapi/openapi.json") }
            pass! { OpenAPIV3, include_str!("../examples/v3.0/json/api-with-examples.json") }
            pass! { OpenAPIV3, include_str!("../examples/v3.0/json/callback-example.json") }
            pass! { OpenAPIV3, include_str!("../examples/v3.0/json/link-example.json") }
            pass! { OpenAPIV3, include_str!("../examples/v3.0/json/petstore-expanded.json") }
            pass! { OpenAPIV3, include_str!("../examples/v3.0/json/petstore.json") }
            pass! { OpenAPIV3, include_str!("../examples/v3.0/json/uspto.json") }
        }
    }
}