paperclip/v2/
mod.rs

1//! Utilities related to the [OpenAPI v2 specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).
2//!
3//! # Detailed example
4//!
5//! To parse your v2 spec, you begin with transforming the schema into a
6//! Rust struct. If your schema doesn't have custom properties, then you
7//! can use the `DefaultSchema`.
8//!
9//! ```rust,no_run
10//! use paperclip::v2::{self, ResolvableApi, DefaultSchema, models::Version};
11//!
12//! use std::fs::File;
13//!
14//! let mut fd = File::open("my_spec.yaml").unwrap(); // yaml or json
15//! let api: ResolvableApi<DefaultSchema> = v2::from_reader(&mut fd).unwrap();
16//! assert_eq!(api.swagger, Version::V2);
17//! ```
18//!
19//! On the other hand, if your schema does have custom properties which you'd
20//! like to parse, then use the `#[api_v2_schema]` proc macro.
21//!
22//! For example, let's take the [Kubernetes API spec][kube-spec]
23//! which uses some custom thingmabobs. Let's say we're only interested in the
24//! `x-kubernetes-patch-strategy` field for now.
25//!
26//! [kube-spec]: https://github.com/kubernetes/kubernetes/tree/afd928b8bc81cea385eba4c94558373df7aeae75/api/openapi-spec
27//!
28//! ```rust,no_run
29//! #[macro_use] extern crate serde_derive; // NOTE: We're using serde for decoding stuff.
30//!
31//! use paperclip::v2::{self, ResolvableApi};
32//!
33//! use std::fs::File;
34//!
35//! #[derive(Debug, Deserialize)]
36//! #[serde(rename_all = "camelCase")]
37//! enum PatchStrategy {
38//!     Merge,
39//!     RetainKeys,
40//!     #[serde(rename = "merge,retainKeys")]
41//!     MergeAndRetain,
42//!     #[serde(other)]
43//!     Other,
44//! }
45//!
46//! #[paperclip::api_v2_schema]
47//! #[derive(Debug, Deserialize)]
48//! struct K8sSchema {
49//!     #[serde(rename = "x-kubernetes-patch-strategy")]
50//!     patch_strategy: Option<PatchStrategy>,
51//! }
52//!
53//! // K8sSchema now implements `Schema` trait.
54//! let mut fd = File::open("k8s_spec.yaml").unwrap();
55//! let api: ResolvableApi<K8sSchema> = v2::from_reader(&mut fd).unwrap();
56//! ```
57//!
58//! Now, if `codegen` feature is enabled (it is by default), we can use the
59//! emitter to emit the API into some path. But first, we need to resolve the
60//! raw schema. During resolution, we:
61//!
62//! - walk through the nodes, find `$ref` fields and assign references to
63//!   the actual definitions.
64//! - identify anonymous definitions in body parameters and response schemas
65//!   and add them to the known map of definitions.
66//!
67//! ```rust,no_run
68//! #[cfg(feature = "codegen")] {
69//! # use paperclip::v2::{self, ResolvableApi, DefaultSchema};
70//! # let api: ResolvableApi<DefaultSchema> = v2::from_reader(&mut std::io::Cursor::new(vec![])).unwrap();
71//!
72//! let resolved = api.resolve().unwrap();
73//! }
74//! ```
75//!
76//! ```rust,no_run
77//! #[cfg(feature = "codegen")] {
78//! # use paperclip::v2::{self, ResolvableApi, DefaultSchema};
79//! # let api: ResolvableApi<DefaultSchema> = v2::from_reader(&mut std::io::Cursor::new(vec![])).unwrap();
80//! use paperclip::v2::{DefaultEmitter, EmitterState, Emitter};
81//!
82//! let mut state = EmitterState::default();
83//! state.working_dir = "/path/to/my/crate".into();
84//! let emitter = DefaultEmitter::from(state);
85//! emitter.generate(&api).unwrap(); // generate code!
86//! }
87//! ```
88
89#[cfg(feature = "codegen")]
90pub mod codegen;
91
92use crate::error::PaperClipError;
93use paperclip_core::v2::models::SpecFormat;
94use serde::Deserialize;
95
96use std::io::Read;
97
98#[cfg(feature = "codegen")]
99pub use self::codegen::{DefaultEmitter, Emitter, EmitterState};
100pub use paperclip_core::{
101    im,
102    v2::{
103        models::{self, DefaultSchema, ResolvableApi},
104        schema::{self, Schema},
105        serde_json,
106    },
107};
108
109/// Deserialize the schema from the given reader. Currently, this only supports
110/// JSON and YAML formats.
111pub fn from_reader<R, S>(mut reader: R) -> Result<ResolvableApi<S>, PaperClipError>
112where
113    R: Read,
114    for<'de> S: Deserialize<'de> + Schema,
115{
116    let mut buf = [b' '];
117    while buf[0].is_ascii_whitespace() {
118        reader.read_exact(&mut buf)?;
119    }
120    let reader = buf.as_ref().chain(reader);
121
122    let (mut api, fmt) = if buf[0] == b'{' {
123        (
124            serde_json::from_reader::<_, ResolvableApi<S>>(reader)?,
125            SpecFormat::Json,
126        )
127    } else {
128        (
129            serde_yaml::from_reader::<_, ResolvableApi<S>>(reader)?,
130            SpecFormat::Yaml,
131        )
132    };
133
134    api.spec_format = fmt;
135    Ok(api)
136}
137
138#[cfg(feature = "cli-ng")]
139/// Deserialize the schema from the given reader. Currently, this only supports
140/// JSON and YAML formats.
141pub fn from_reader_v3<R>(mut reader: R) -> Result<openapiv3::OpenAPI, PaperClipError>
142where
143    R: Read,
144{
145    let mut buf = [b' '];
146    while buf[0].is_ascii_whitespace() {
147        reader.read_exact(&mut buf)?;
148    }
149    let reader = buf.as_ref().chain(reader);
150
151    let (api, _fmt) = if buf[0] == b'{' {
152        (
153            serde_json::from_reader::<_, openapiv3::OpenAPI>(reader)?,
154            SpecFormat::Json,
155        )
156    } else {
157        (
158            serde_yaml::from_reader::<_, openapiv3::OpenAPI>(reader)?,
159            SpecFormat::Yaml,
160        )
161    };
162
163    Ok(api)
164}
paperclip/v2/mod.rs

paperclip/v2/
mod.rs
