Skip to content

Commit b2bd4cd

Browse files
committed
chore: fixes indentation in code snippets
Signed-off-by: Vincent Biret <[email protected]>
1 parent 6c1a630 commit b2bd4cd

File tree

1 file changed

+88
-97
lines changed

1 file changed

+88
-97
lines changed

docs/upgrade-guide-2.md

Lines changed: 88 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -149,58 +149,58 @@ In v2 we are removing this abstraction and relying on the `JsonNode` model to re
149149
Due 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

161161
the assignment becomes simply,
162162

163163
```csharp
164-
Example = 0.5f,
164+
Example = 0.5f,
165165
```
166166

167167
For 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

187187
In 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

324323
Other 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

404395
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.
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

Comments
 (0)