forge-ir 0.1.6

OpenAPI Forge intermediate representation types
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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286

//! Operations, parameters, request bodies, and responses.

use serde::{Deserialize, Serialize};

use crate::diagnostic::SpecLocation;
use crate::security::SecurityRequirement;
use crate::types::TypeRef;
use crate::value::ValueRef;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Operation {
    pub id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub original_id: Option<String>,
    pub method: HttpMethod,
    pub path_template: String,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub path_params: Vec<Parameter>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub query_params: Vec<Parameter>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub header_params: Vec<Parameter>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub cookie_params: Vec<Parameter>,
    /// OAS 3.2 `in: querystring` parameters — bind to the *entire*
    /// query string (opaque pass-through). Spec semantics imply at most
    /// one entry per operation; the parser warns rather than errors if
    /// a spec declares multiple, and the IR carries them as a list for
    /// uniformity with the other location buckets.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub querystring_params: Vec<Parameter>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub request_body: Option<Body>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub responses: Vec<Response>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub security: Vec<SecurityRequirement>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub documentation: Option<String>,
    #[serde(default)]
    pub deprecated: bool,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub extensions: Vec<(String, ValueRef)>,
    /// Per-operation `externalDocs` (OAS Operation Object).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub external_docs: Option<crate::ExternalDocs>,
    /// Effective `servers` list for this operation. The parser
    /// resolves OAS §4.8.10 inheritance — operation-level entries win
    /// over path-item entries, which win over the root list — and
    /// materialises the result here. Empty if neither this operation,
    /// its path item, nor the root declared any servers.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub servers: Vec<crate::Server>,
    /// OAS Callback Objects — out-of-band requests the API makes back
    /// to the caller (event-driven / webhook APIs). Each entry pairs a
    /// callback name with one runtime expression (e.g.
    /// `{$request.body#/callbackUrl}`); a single callback name with
    /// multiple expressions becomes multiple entries.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub callbacks: Vec<crate::Callback>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub location: Option<SpecLocation>,
}

/// HTTP method for an operation. The eight standard verbs plus an
/// `Other(String)` escape hatch that carries 3.2 `additionalOperations`
/// methods (e.g. RFC 9205 `QUERY`) verbatim. Generators that emit
/// against a fixed verb set should match the named variants and either
/// reject `Other` (with a `StageError::Rejected`) or pass the string
/// through to a lower-level builder API.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum HttpMethod {
    Get,
    Put,
    Post,
    Delete,
    Options,
    Head,
    Patch,
    Trace,
    /// Carries the upper-cased method name (`"QUERY"`, etc.).
    Other(String),
}

impl HttpMethod {
    /// Wire-form of the method (uppercased verb that goes on the
    /// request line). Use this when serialising to HTTP.
    pub fn as_str(&self) -> &str {
        match self {
            HttpMethod::Get => "GET",
            HttpMethod::Put => "PUT",
            HttpMethod::Post => "POST",
            HttpMethod::Delete => "DELETE",
            HttpMethod::Options => "OPTIONS",
            HttpMethod::Head => "HEAD",
            HttpMethod::Patch => "PATCH",
            HttpMethod::Trace => "TRACE",
            HttpMethod::Other(s) => s,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Parameter {
    pub name: String,
    #[serde(rename = "type")]
    pub r#type: TypeRef,
    pub required: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub documentation: Option<String>,
    #[serde(default)]
    pub deprecated: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub style: Option<ParameterStyle>,
    #[serde(default)]
    pub explode: bool,
    /// OAS `allowEmptyValue`. Permits `?foo=` with no value. Only legal
    /// on `in: query`; the parser warns and clears it for other
    /// locations.
    #[serde(default)]
    pub allow_empty_value: bool,
    /// OAS `allowReserved`. Permits raw RFC 3986 reserved chars in the
    /// rendered query string. Defaults to `false`.
    #[serde(default)]
    pub allow_reserved: bool,
    /// OAS `example` / `examples` for this parameter. Named entries;
    /// 3.0 `example: <literal>` lands under the synthetic key
    /// `"_default"`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub examples: Vec<(String, crate::Example)>,
    /// `x-*` extensions declared on the parameter. Compound extensions
    /// drop with `parser/W-EXTENSION-DROPPED`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub extensions: Vec<(String, ValueRef)>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub location: Option<SpecLocation>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ParameterStyle {
    Form,
    Simple,
    Label,
    Matrix,
    SpaceDelimited,
    PipeDelimited,
    DeepObject,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Body {
    pub content: Vec<BodyContent>,
    pub required: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub documentation: Option<String>,
    /// `x-*` extensions declared on the request-body object. Compound
    /// extensions drop with `parser/W-EXTENSION-DROPPED`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub extensions: Vec<(String, ValueRef)>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BodyContent {
    pub media_type: String,
    #[serde(rename = "type")]
    pub r#type: TypeRef,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub encoding: Vec<(String, Encoding)>,
    /// OAS 3.2 `itemSchema`: per-item shape for sequence-of-items
    /// responses (JSON Lines, SSE event-stream, multipart/mixed).
    /// Mutually exclusive with `schema` in the spec; when present, the
    /// parser populates `type` with the same ref so generators that
    /// don't model streaming see a usable type. Streaming-aware
    /// generators read `item_schema` to know they should decode one
    /// record at a time.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub item_schema: Option<TypeRef>,
    /// OAS `example` / `examples` for this media-type entry. Named
    /// entries; 3.0 `example: <literal>` lands under the synthetic
    /// key `"_default"`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub examples: Vec<(String, crate::Example)>,
    /// `x-*` extensions declared on the media-type object. Compound
    /// extensions drop with `parser/W-EXTENSION-DROPPED`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub extensions: Vec<(String, ValueRef)>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Encoding {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub content_type: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub style: Option<ParameterStyle>,
    #[serde(default)]
    pub explode: bool,
    /// OAS `allowReserved`. When `true`, RFC 3986 reserved characters
    /// (`:/?#[]@!$&'()*+,;=`) are passed through verbatim instead of
    /// being percent-encoded; meaningful for
    /// `application/x-www-form-urlencoded` parts. Defaults to `false`.
    #[serde(default)]
    pub allow_reserved: bool,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub headers: Vec<(String, Header)>,
    /// `x-*` extensions declared on the encoding object. Compound
    /// extensions drop with `parser/W-EXTENSION-DROPPED`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub extensions: Vec<(String, ValueRef)>,
}

/// OAS Header Object. Distinct from [`Parameter`] because headers
/// have a fixed serialization style (no `style`/`explode`), and
/// because `required` carries different semantics here:
/// "documented as always present in the response" rather than "the
/// request must include this".
///
/// The header's name lives on the surrounding tuple key
/// (`Vec<(String, Header)>`), not on this struct.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Header {
    #[serde(rename = "type")]
    pub r#type: TypeRef,
    #[serde(default)]
    pub required: bool,
    #[serde(default)]
    pub deprecated: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub documentation: Option<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub examples: Vec<(String, crate::Example)>,
    /// OAS Header Object inherits the Parameter Object's serialization
    /// fields. The spec fixes `style` to `simple` for headers, but
    /// captures the value verbatim so spec-strict consumers
    /// (validators, doc generators) can see what was declared. Most
    /// generators ignore this slot.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub style: Option<ParameterStyle>,
    /// OAS `explode`. Defaults to `false` per Header Object semantics.
    #[serde(default)]
    pub explode: bool,
    /// OAS `allowReserved`. Permits raw RFC 3986 reserved characters
    /// in the rendered header value. Defaults to `false`.
    #[serde(default)]
    pub allow_reserved: bool,
    /// OAS `allowEmptyValue`. Defaults to `false`.
    #[serde(default)]
    pub allow_empty_value: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub location: Option<SpecLocation>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Response {
    pub status: ResponseStatus,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub content: Vec<BodyContent>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub headers: Vec<(String, Header)>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub documentation: Option<String>,
    /// OAS `links` — HATEOAS follow-ups. Named entries; order is
    /// preserved.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub links: Vec<(String, crate::Link)>,
    /// `x-*` extensions declared on the response object. Compound
    /// extensions drop with `parser/W-EXTENSION-DROPPED`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub extensions: Vec<(String, ValueRef)>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
pub enum ResponseStatus {
    Explicit {
        code: u16,
    },
    Default,
    /// A status range from `1` (1xx) through `5` (5xx).
    Range {
        class: u8,
    },
}