@@ -149,58 +149,58 @@ In v2 we are removing this abstraction and relying on the `JsonNode` model to re
149
149
Due to ` JsonNode ` implicit operators, this makes initialization sometimes easier, instead of:
150
150
151
151
``` csharp
152
- new OpenApiParameter
153
- {
154
- In = null ,
155
- Name = " username" ,
156
- Description = " username to fetch" ,
157
- Example = new OpenApiFloat (5 ),
158
- };
152
+ new OpenApiParameter
153
+ {
154
+ In = null ,
155
+ Name = " username" ,
156
+ Description = " username to fetch" ,
157
+ Example = new OpenApiFloat (5 ),
158
+ };
159
159
```
160
160
161
161
the assignment becomes simply,
162
162
163
163
``` csharp
164
- Example = 0 . 5 f ,
164
+ Example = 0 . 5 f ,
165
165
```
166
166
167
167
For a more complex example, where the developer wants to create an extension that is an object they would do this in v1:
168
168
169
169
``` csharp
170
- var openApiObject = new OpenApiObject
171
- {
172
- {" stringProp" , new OpenApiString (" stringValue1" )},
173
- {" objProp" , new OpenApiObject ()},
174
- {
175
- " arrayProp" ,
176
- new OpenApiArray
177
- {
178
- new OpenApiBoolean (false )
179
- }
180
- }
181
- };
182
- var parameter = new OpenApiParameter ();
183
- parameter .Extensions .Add (" x-foo" , new OpenApiAny (openApiObject ));
170
+ var openApiObject = new OpenApiObject
171
+ {
172
+ {" stringProp" , new OpenApiString (" stringValue1" )},
173
+ {" objProp" , new OpenApiObject ()},
174
+ {
175
+ " arrayProp" ,
176
+ new OpenApiArray
177
+ {
178
+ new OpenApiBoolean (false )
179
+ }
180
+ }
181
+ };
182
+ var parameter = new OpenApiParameter ();
183
+ parameter .Extensions .Add (" x-foo" , new OpenApiAny (openApiObject ));
184
184
185
185
```
186
186
187
187
In v2, the equivalent code would be,
188
188
189
189
``` csharp
190
- var openApiObject = new JsonObject
191
- {
192
- {" stringProp" , " stringValue1" },
193
- {" objProp" , new JsonObject ()},
194
- {
195
- " arrayProp" ,
196
- new JsonArray
197
- {
198
- false
199
- }
200
- }
201
- };
202
- var parameter = new OpenApiParameter ();
203
- parameter .Extensions .Add (" x-foo" , new OpenApiAny (openApiObject ));
190
+ var openApiObject = new JsonObject
191
+ {
192
+ {" stringProp" , " stringValue1" },
193
+ {" objProp" , new JsonObject ()},
194
+ {
195
+ " arrayProp" ,
196
+ new JsonArray
197
+ {
198
+ false
199
+ }
200
+ }
201
+ };
202
+ var parameter = new OpenApiParameter ();
203
+ parameter .Extensions .Add (" x-foo" , new OpenApiAny (openApiObject ));
204
204
205
205
```
206
206
@@ -298,39 +298,38 @@ The OpenAPI 3.1 specification changes significantly how it leverages JSON Schema
298
298
#### Changes to existing keywords
299
299
300
300
``` csharp
301
-
302
- public string ? ExclusiveMaximum { get ; set ; } // type changed to reflect the new version of JSON schema
303
- public string ? ExclusiveMinimum { get ; set ; } // type changed to reflect the new version of JSON schema
304
- public JsonSchemaType ? Type { get ; set ; } // Was string, now flagged enum
305
- public string ? Maximum { get ; set ; } // type changed to overcome double vs decimal issues
306
- public string ? Minimum { get ; set ; } // type changed to overcome double vs decimal issues
307
-
308
- public JsonNode Default { get ; set ; } // Type matching no longer enforced. Was IOpenApiAny
309
- public bool ReadOnly { get ; set ; } // No longer has defined semantics in OpenAPI 3.1
310
- public bool WriteOnly { get ; set ; } // No longer has defined semantics in OpenAPI 3.1
311
-
312
- public JsonNode Example { get ; set ; } // No longer IOpenApiAny
313
- public IList < JsonNode > Examples { get ; set ; }
314
- public IList < JsonNode > Enum { get ; set ; }
315
- public OpenApiExternalDocs ExternalDocs { get ; set ; } // OpenApi Vocab
316
- public bool Deprecated { get ; set ; } // OpenApi Vocab
317
- public OpenApiXml Xml { get ; set ; } // OpenApi Vocab
318
-
319
- public IDictionary < string , object > Metadata { get ; set ; } // Custom property bag to be used by the application, used to be named annotations
301
+ public string ? ExclusiveMaximum { get ; set ; } // type changed to reflect the new version of JSON schema
302
+ public string ? ExclusiveMinimum { get ; set ; } // type changed to reflect the new version of JSON schema
303
+ public JsonSchemaType ? Type { get ; set ; } // Was string, now flagged enum
304
+ public string ? Maximum { get ; set ; } // type changed to overcome double vs decimal issues
305
+ public string ? Minimum { get ; set ; } // type changed to overcome double vs decimal issues
306
+
307
+ public JsonNode Default { get ; set ; } // Type matching no longer enforced. Was IOpenApiAny
308
+ public bool ReadOnly { get ; set ; } // No longer has defined semantics in OpenAPI 3.1
309
+ public bool WriteOnly { get ; set ; } // No longer has defined semantics in OpenAPI 3.1
310
+
311
+ public JsonNode Example { get ; set ; } // No longer IOpenApiAny
312
+ public IList < JsonNode > Examples { get ; set ; }
313
+ public IList < JsonNode > Enum { get ; set ; }
314
+ public OpenApiExternalDocs ExternalDocs { get ; set ; } // OpenApi Vocab
315
+ public bool Deprecated { get ; set ; } // OpenApi Vocab
316
+ public OpenApiXml Xml { get ; set ; } // OpenApi Vocab
317
+
318
+ public IDictionary < string , object > Metadata { get ; set ; } // Custom property bag to be used by the application, used to be named annotations
320
319
```
321
320
322
321
#### OpenApiSchema methods
323
322
324
323
Other than the addition of ` SerializeAsV31 ` , the methods have not changed.
325
324
326
325
``` csharp
327
- public class OpenApiSchema : IOpenApiAnnotatable , IOpenApiExtensible , IOpenApiReferenceable , IOpenApiSerializable
326
+ public class OpenApiSchema : IOpenApiMetadataContainer , IOpenApiExtensible , IOpenApiReferenceable , IOpenApiSerializable
328
327
{
329
- public OpenApiSchema () { }
330
- public OpenApiSchema (OpenApiSchema schema ) { }
331
- public void SerializeAsV31 (IOpenApiWriter writer ) { }
332
- public void SerializeAsV3 (IOpenApiWriter writer ) { }
333
- public void SerializeAsV2 (IOpenApiWriter writer ) { }
328
+ public OpenApiSchema () { }
329
+ public OpenApiSchema (OpenApiSchema schema ) { }
330
+ public void SerializeAsV31 (IOpenApiWriter writer ) { }
331
+ public void SerializeAsV3 (IOpenApiWriter writer ) { }
332
+ public void SerializeAsV2 (IOpenApiWriter writer ) { }
334
333
}
335
334
336
335
```
@@ -343,71 +342,63 @@ There are a number of new features in OpenAPI v3.1 that are now supported in Ope
343
342
344
343
``` csharp
345
344
346
- public class OpenApiDocument : IOpenApiSerializable , IOpenApiExtensible , IOpenApiAnnotatable {
347
- /// <summary >
348
- /// The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement.
349
- /// A map of requests initiated other than by an API call, for example by an out of band registration.
350
- /// The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses
351
- /// </summary >
352
- public IDictionary <string , OpenApiPathItem >? Webhooks { get ; set ; } = new Dictionary <string , OpenApiPathItem >();
345
+ public class OpenApiDocument : IOpenApiSerializable , IOpenApiExtensible , IOpenApiMetadataContainer
346
+ {
347
+ public IDictionary <string , OpenApiPathItem >? Webhooks { get ; set ; } = new Dictionary <string , OpenApiPathItem >();
353
348
}
354
349
```
355
350
356
351
### Summary in info object
357
352
358
353
``` csharp
359
-
354
+ public class OpenApiInfo : IOpenApiSerializable , IOpenApiExtensible
355
+ {
360
356
/// <summary >
361
- /// Open API Info Object, it provides the metadata about the Open API.
357
+ /// A short summary of the API.
362
358
/// </summary >
363
- public class OpenApiInfo : IOpenApiSerializable , IOpenApiExtensible
364
- {
365
- /// <summary >
366
- /// A short summary of the API.
367
- /// </summary >
368
- public string Summary { get ; set ; }
369
- }
359
+ public string Summary { get ; set ; }
360
+ }
370
361
```
371
362
372
363
### License SPDX identifiers
373
364
374
365
``` csharp
366
+ /// <summary >
367
+ /// License Object.
368
+ /// </summary >
369
+ public class OpenApiLicense : IOpenApiSerializable , IOpenApiExtensible
370
+ {
375
371
/// <summary >
376
- /// License Object .
372
+ /// An SPDX license expression for the API. The identifier field is mutually exclusive of the Url property .
377
373
/// </summary >
378
- public class OpenApiLicense : IOpenApiSerializable , IOpenApiExtensible
379
- {
380
- /// <summary >
381
- /// An SPDX license expression for the API. The identifier field is mutually exclusive of the Url property.
382
- /// </summary >
383
- public string Identifier { get ; set ; }
384
- }
374
+ public string Identifier { get ; set ; }
375
+ }
385
376
```
386
377
387
378
### Reusable path items
388
379
389
380
``` csharp
381
+ /// <summary >
382
+ /// Components Object.
383
+ /// </summary >
384
+ public class OpenApiComponents : IOpenApiSerializable , IOpenApiExtensible
385
+ {
390
386
/// <summary >
391
- /// Components Object.
387
+ /// An object to hold reusable < see cref = " OpenApiPathItem " /> Object.
392
388
/// </summary >
393
- public class OpenApiComponents : IOpenApiSerializable , IOpenApiExtensible
394
- {
395
- /// <summary >
396
- /// An object to hold reusable <see cref =" OpenApiPathItem" /> Object.
397
- /// </summary >
398
- public IDictionary <string , OpenApiPathItem >? PathItems { get ; set ; } = new Dictionary <string , OpenApiPathItem >();
399
- }
389
+ public IDictionary <string , OpenApiPathItem >? PathItems { get ; set ; } = new Dictionary <string , OpenApiPathItem >();
390
+ }
400
391
```
401
392
402
393
#### Summary and Description alongside $ref
403
394
404
395
Through the use of proxy objects in order to represent references, it is now possible to set the Summary and Description property on an object that is a reference. This was previously not possible.
405
396
406
397
``` csharp
407
- var parameter = new OpenApiParameterReference (" id" , hostdocument )
408
- {
409
- Description = " Customer Id"
410
- };
398
+ var parameter = new OpenApiParameterReference (" id" , hostdocument )
399
+ {
400
+ Description = " Customer Id"
401
+ };
411
402
```
412
403
413
404
### Use HTTP Method Object Instead of Enum
0 commit comments