-
Notifications
You must be signed in to change notification settings - Fork 224
/
OpenApiParameter.cs
441 lines (379 loc) · 17.7 KB
/
OpenApiParameter.cs
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
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT license.
using System;
using System.Collections.Generic;
using Json.Schema;
using System.Linq;
using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Extensions;
using Microsoft.OpenApi.Helpers;
using Microsoft.OpenApi.Interfaces;
using Microsoft.OpenApi.Writers;
namespace Microsoft.OpenApi.Models
{
/// <summary>
/// Parameter Object.
/// </summary>
public class OpenApiParameter : IOpenApiReferenceable, IOpenApiExtensible
{
private bool? _explode;
private ParameterStyle? _style;
private JsonSchema _schema;
/// <summary>
/// Indicates if object is populated with data or is just a reference to the data
/// </summary>
public virtual bool UnresolvedReference { get; set; }
/// <summary>
/// Reference object.
/// </summary>
public OpenApiReference Reference { get; set; }
/// <summary>
/// REQUIRED. The name of the parameter. Parameter names are case sensitive.
/// If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object.
/// If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.
/// For all other cases, the name corresponds to the parameter name used by the in property.
/// </summary>
public virtual string Name { get; set; }
/// <summary>
/// REQUIRED. The location of the parameter.
/// Possible values are "query", "header", "path" or "cookie".
/// </summary>
public virtual ParameterLocation? In { get; set; }
/// <summary>
/// A brief description of the parameter. This could contain examples of use.
/// CommonMark syntax MAY be used for rich text representation.
/// </summary>
public virtual string Description { get; set; }
/// <summary>
/// Determines whether this parameter is mandatory.
/// If the parameter location is "path", this property is REQUIRED and its value MUST be true.
/// Otherwise, the property MAY be included and its default value is false.
/// </summary>
public virtual bool Required { get; set; }
/// <summary>
/// Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.
/// </summary>
public virtual bool Deprecated { get; set; } = false;
/// <summary>
/// Sets the ability to pass empty-valued parameters.
/// This is valid only for query parameters and allows sending a parameter with an empty value.
/// Default value is false.
/// If style is used, and if behavior is n/a (cannot be serialized),
/// the value of allowEmptyValue SHALL be ignored.
/// </summary>
public virtual bool AllowEmptyValue { get; set; } = false;
/// <summary>
/// Describes how the parameter value will be serialized depending on the type of the parameter value.
/// Default values (based on value of in): for query - form; for path - simple; for header - simple;
/// for cookie - form.
/// </summary>
public virtual ParameterStyle? Style
{
get => _style ?? GetDefaultStyleValue();
set => _style = value;
}
/// <summary>
/// When this is true, parameter values of type array or object generate separate parameters
/// for each value of the array or key-value pair of the map.
/// For other types of parameters this property has no effect.
/// When style is form, the default value is true.
/// For all other styles, the default value is false.
/// </summary>
public virtual bool Explode
{
get => _explode ?? Style == ParameterStyle.Form;
set => _explode = value;
}
/// <summary>
/// Determines whether the parameter value SHOULD allow reserved characters,
/// as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.
/// This property only applies to parameters with an in value of query.
/// The default value is false.
/// </summary>
public virtual bool AllowReserved { get; set; }
/// <summary>
/// The schema defining the type used for the parameter.
/// </summary>
public virtual JsonSchema Schema
{
get => _schema;
set => _schema = value;
}
/// <summary>
/// Examples of the media type. Each example SHOULD contain a value
/// in the correct format as specified in the parameter encoding.
/// The examples object is mutually exclusive of the example object.
/// Furthermore, if referencing a schema which contains an example,
/// the examples value SHALL override the example provided by the schema.
/// </summary>
public virtual IDictionary<string, OpenApiExample> Examples { get; set; } = new Dictionary<string, OpenApiExample>();
/// <summary>
/// Example of the media type. The example SHOULD match the specified schema and encoding properties
/// if present. The example object is mutually exclusive of the examples object.
/// Furthermore, if referencing a schema which contains an example,
/// the example value SHALL override the example provided by the schema.
/// To represent examples of media types that cannot naturally be represented in JSON or YAML,
/// a string value can contain the example with escaping where necessary.
/// </summary>
public virtual OpenApiAny Example { get; set; }
/// <summary>
/// A map containing the representations for the parameter.
/// The key is the media type and the value describes it.
/// The map MUST only contain one entry.
/// For more complex scenarios, the content property can define the media type and schema of the parameter.
/// A parameter MUST contain either a schema property, or a content property, but not both.
/// When example or examples are provided in conjunction with the schema object,
/// the example MUST follow the prescribed serialization strategy for the parameter.
/// </summary>
public virtual IDictionary<string, OpenApiMediaType> Content { get; set; } = new Dictionary<string, OpenApiMediaType>();
/// <summary>
/// This object MAY be extended with Specification Extensions.
/// </summary>
public virtual IDictionary<string, IOpenApiExtension> Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
/// <summary>
/// A parameterless constructor
/// </summary>
public OpenApiParameter() { }
/// <summary>
/// Initializes a clone instance of <see cref="OpenApiParameter"/> object
/// </summary>
public OpenApiParameter(OpenApiParameter parameter)
{
UnresolvedReference = parameter?.UnresolvedReference ?? UnresolvedReference;
Reference = parameter?.Reference != null ? new(parameter?.Reference) : null;
Name = parameter?.Name ?? Name;
In = parameter?.In ?? In;
Description = parameter?.Description ?? Description;
Required = parameter?.Required ?? Required;
Style = parameter?.Style ?? Style;
Explode = parameter?.Explode ?? Explode;
AllowReserved = parameter?.AllowReserved ?? AllowReserved;
Schema = parameter?.Schema != null ? JsonNodeCloneHelper.CloneJsonSchema(parameter.Schema) : null;
Examples = parameter?.Examples != null ? new Dictionary<string, OpenApiExample>(parameter.Examples) : null;
Example = parameter?.Example != null ? JsonNodeCloneHelper.Clone(parameter.Example) : null;
Content = parameter?.Content != null ? new Dictionary<string, OpenApiMediaType>(parameter.Content) : null;
Extensions = parameter?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(parameter.Extensions) : null;
AllowEmptyValue = parameter?.AllowEmptyValue ?? AllowEmptyValue;
Deprecated = parameter?.Deprecated ?? Deprecated;
}
/// <summary>
/// Serialize <see cref="OpenApiParameter"/> to Open Api v3.1
/// </summary>
public virtual void SerializeAsV31(IOpenApiWriter writer)
{
SerializeInternal(writer, (writer, element) => element.SerializeAsV31(writer),
(writer, element) => element.SerializeAsV31WithoutReference(writer));
}
/// <summary>
/// Serialize <see cref="OpenApiParameter"/> to Open Api v3.0
/// </summary>
public virtual void SerializeAsV3(IOpenApiWriter writer)
{
SerializeInternal(writer, (writer, element) => element.SerializeAsV3(writer),
(writer, element) => element.SerializeAsV3WithoutReference(writer));
}
private void SerializeInternal(IOpenApiWriter writer, Action<IOpenApiWriter, IOpenApiSerializable> callback,
Action<IOpenApiWriter, IOpenApiReferenceable> action)
{
Utils.CheckArgumentNull(writer);;
var target = this;
action(writer, target);
}
/// <summary>
/// Serialize to OpenAPI V3 document without using reference.
/// </summary>
public virtual void SerializeAsV31WithoutReference(IOpenApiWriter writer)
{
SerializeInternalWithoutReference(writer, OpenApiSpecVersion.OpenApi3_1,
(writer, element) => element.SerializeAsV31(writer));
}
/// <summary>
/// Serialize to OpenAPI V3 document without using reference.
/// </summary>
public virtual void SerializeAsV3WithoutReference(IOpenApiWriter writer)
{
SerializeInternalWithoutReference(writer, OpenApiSpecVersion.OpenApi3_0,
(writer, element) => element.SerializeAsV3(writer));
}
internal virtual void SerializeInternalWithoutReference(IOpenApiWriter writer, OpenApiSpecVersion version,
Action<IOpenApiWriter, IOpenApiSerializable> callback)
{
writer.WriteStartObject();
// name
writer.WriteProperty(OpenApiConstants.Name, Name);
// in
writer.WriteProperty(OpenApiConstants.In, In?.GetDisplayName());
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// required
writer.WriteProperty(OpenApiConstants.Required, Required, false);
// deprecated
writer.WriteProperty(OpenApiConstants.Deprecated, Deprecated, false);
// allowEmptyValue
writer.WriteProperty(OpenApiConstants.AllowEmptyValue, AllowEmptyValue, false);
// style
if (_style.HasValue)
{
writer.WriteProperty(OpenApiConstants.Style, _style.Value.GetDisplayName());
}
// explode
writer.WriteProperty(OpenApiConstants.Explode, _explode, _style is ParameterStyle.Form);
// allowReserved
writer.WriteProperty(OpenApiConstants.AllowReserved, AllowReserved, false);
// schema
if (Schema != null)
{
writer.WritePropertyName(OpenApiConstants.Schema);
writer.WriteJsonSchema(Schema, version);
}
// example
writer.WriteOptionalObject(OpenApiConstants.Example, Example, (w, s) => w.WriteAny(s));
// examples
writer.WriteOptionalMap(OpenApiConstants.Examples, Examples, callback);
// content
writer.WriteOptionalMap(OpenApiConstants.Content, Content, callback);
// extensions
writer.WriteExtensions(Extensions, version);
writer.WriteEndObject();
}
/// <summary>
/// Serialize <see cref="OpenApiParameter"/> to Open Api v2.0
/// </summary>
public virtual void SerializeAsV2(IOpenApiWriter writer)
{
Utils.CheckArgumentNull(writer);;
var target = this;
target.SerializeAsV2WithoutReference(writer);
}
/// <summary>
/// Serialize to OpenAPI V2 document without using reference.
/// </summary>
public void SerializeAsV2WithoutReference(IOpenApiWriter writer)
{
writer.WriteStartObject();
// in
if (this is OpenApiFormDataParameter)
{
writer.WriteProperty(OpenApiConstants.In, "formData");
}
else if (this is OpenApiBodyParameter)
{
writer.WriteProperty(OpenApiConstants.In, "body");
}
else
{
writer.WriteProperty(OpenApiConstants.In, In?.GetDisplayName());
}
// name
writer.WriteProperty(OpenApiConstants.Name, Name);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// required
writer.WriteProperty(OpenApiConstants.Required, Required, false);
// deprecated
writer.WriteProperty(OpenApiConstants.Deprecated, Deprecated, false);
var extensionsClone = new Dictionary<string, IOpenApiExtension>(Extensions);
// schema
if (this is OpenApiBodyParameter)
{
writer.WriteOptionalObject(OpenApiConstants.Schema, Schema, (w, s) => writer.WriteJsonSchema(s, OpenApiSpecVersion.OpenApi2_0));
}
// In V2 parameter's type can't be a reference to a custom object schema or can't be of type object
// So in that case map the type as string.
else if (Schema?.GetJsonType() == SchemaValueType.Object)
{
writer.WriteProperty(OpenApiConstants.Type, "string");
}
else
{
// type
// format
// items
// collectionFormat
// default
// maximum
// exclusiveMaximum
// minimum
// exclusiveMinimum
// maxLength
// minLength
// pattern
// maxItems
// minItems
// uniqueItems
// enum
// multipleOf
if (Schema != null)
{
SchemaSerializerHelper.WriteAsItemsProperties(Schema, writer, Extensions, OpenApiSpecVersion.OpenApi2_0);
var extensions = Schema.GetExtensions();
if (extensions != null)
{
foreach (var key in extensions.Keys)
{
// The extension will already have been serialized as part of the call to WriteAsItemsProperties above,
// so remove it from the cloned collection so we don't write it again.
extensionsClone.Remove(key);
}
}
}
// allowEmptyValue
writer.WriteProperty(OpenApiConstants.AllowEmptyValue, AllowEmptyValue, false);
if (this.In == ParameterLocation.Query && SchemaValueType.Array.Equals(Schema?.GetJsonType()))
{
if (this.Style == ParameterStyle.Form && this.Explode == true)
{
writer.WriteProperty("collectionFormat", "multi");
}
else if (this.Style == ParameterStyle.PipeDelimited)
{
writer.WriteProperty("collectionFormat", "pipes");
}
else if (this.Style == ParameterStyle.SpaceDelimited)
{
writer.WriteProperty("collectionFormat", "ssv");
}
}
}
//examples
if (Examples != null && Examples.Any())
{
writer.WritePropertyName(OpenApiConstants.ExamplesExtension);
writer.WriteStartObject();
foreach (var example in Examples)
{
writer.WritePropertyName(example.Key);
example.Value.Serialize(writer, OpenApiSpecVersion.OpenApi2_0);
}
writer.WriteEndObject();
}
// extensions
writer.WriteExtensions(extensionsClone, OpenApiSpecVersion.OpenApi2_0);
writer.WriteEndObject();
}
internal virtual ParameterStyle? GetDefaultStyleValue()
{
Style = In switch
{
ParameterLocation.Query => ParameterStyle.Form,
ParameterLocation.Header => ParameterStyle.Simple,
ParameterLocation.Path => ParameterStyle.Simple,
ParameterLocation.Cookie => ParameterStyle.Form,
_ => (ParameterStyle?)ParameterStyle.Simple,
};
return Style;
}
}
/// <summary>
/// Body parameter class to propagate information needed for <see cref="OpenApiParameter.SerializeAsV2"/>
/// </summary>
internal class OpenApiBodyParameter : OpenApiParameter
{
}
/// <summary>
/// Form parameter class to propagate information needed for <see cref="OpenApiParameter.SerializeAsV2"/>
/// </summary>
internal class OpenApiFormDataParameter : OpenApiParameter
{
}
}