@@ -149,58 +149,58 @@ In v2 we are removing this abstraction and relying on the `JsonNode` model to re
149149Due to ` JsonNode ` implicit operators, this makes initialization sometimes easier, instead of:
150150
151151``` 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+ };
159159```
160160
161161the assignment becomes simply,
162162
163163``` csharp
164- Example = 0 . 5 f ,
164+ Example = 0 . 5 f ,
165165```
166166
167167For a more complex example, where the developer wants to create an extension that is an object they would do this in v1:
168168
169169``` 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 ));
184184
185185```
186186
187187In v2, the equivalent code would be,
188188
189189``` 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 ));
204204
205205```
206206
@@ -298,39 +298,38 @@ The OpenAPI 3.1 specification changes significantly how it leverages JSON Schema
298298#### Changes to existing keywords
299299
300300``` 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
320319```
321320
322321#### OpenApiSchema methods
323322
324323Other than the addition of ` SerializeAsV31 ` , the methods have not changed.
325324
326325``` csharp
327- public class OpenApiSchema : IOpenApiAnnotatable , IOpenApiExtensible , IOpenApiReferenceable , IOpenApiSerializable
326+ public class OpenApiSchema : IOpenApiMetadataContainer , IOpenApiExtensible , IOpenApiReferenceable , IOpenApiSerializable
328327{
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 ) { }
334333}
335334
336335```
@@ -343,71 +342,63 @@ There are a number of new features in OpenAPI v3.1 that are now supported in Ope
343342
344343``` csharp
345344
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 >();
353348}
354349```
355350
356351### Summary in info object
357352
358353``` csharp
359-
354+ public class OpenApiInfo : IOpenApiSerializable , IOpenApiExtensible
355+ {
360356 /// <summary >
361- /// Open API Info Object, it provides the metadata about the Open API.
357+ /// A short summary of the API.
362358 /// </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+ }
370361```
371362
372363### License SPDX identifiers
373364
374365``` csharp
366+ /// <summary >
367+ /// License Object.
368+ /// </summary >
369+ public class OpenApiLicense : IOpenApiSerializable , IOpenApiExtensible
370+ {
375371 /// <summary >
376- /// License Object .
372+ /// An SPDX license expression for the API. The identifier field is mutually exclusive of the Url property .
377373 /// </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+ }
385376```
386377
387378### Reusable path items
388379
389380``` csharp
381+ /// <summary >
382+ /// Components Object.
383+ /// </summary >
384+ public class OpenApiComponents : IOpenApiSerializable , IOpenApiExtensible
385+ {
390386 /// <summary >
391- /// Components Object.
387+ /// An object to hold reusable < see cref = " OpenApiPathItem " /> Object.
392388 /// </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+ }
400391```
401392
402393#### Summary and Description alongside $ref
403394
404395Through 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.
405396
406397``` 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+ };
411402```
412403
413404### Use HTTP Method Object Instead of Enum
0 commit comments