/// <summary>
/// Serialize <see cref="OpenApiPathItem"/> to Open Api v3.0
/// </summary>
public void SerializeAsV3(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// summary
writer.WriteProperty(OpenApiConstants.Summary, Summary);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// operations
foreach (var operation in Operations)
{
writer.WriteOptionalObject(
operation.Key.GetDisplayName(),
operation.Value,
(w, o) => o.SerializeAsV3(w));
}
// servers
writer.WriteOptionalCollection(OpenApiConstants.Servers, Servers, (w, s) => s.SerializeAsV3(w));
// parameters
writer.WriteOptionalCollection(OpenApiConstants.Parameters, Parameters, (w, p) => p.SerializeAsV3(w));
// specification extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
/// <summary>
/// Serialize inline PathItem in OpenAPI V3
/// </summary>
/// <param name="writer"></param>
public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
{
writer.WriteStartObject();
// summary
writer.WriteProperty(OpenApiConstants.Summary, Summary);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// operations
foreach (var operation in Operations)
{
writer.WriteOptionalObject(
operation.Key.GetDisplayName(),
operation.Value,
(w, o) => o.SerializeAsV3(w));
}
// servers
writer.WriteOptionalCollection(OpenApiConstants.Servers, Servers, (w, s) => s.SerializeAsV3(w));
// parameters
writer.WriteOptionalCollection(OpenApiConstants.Parameters, Parameters, (w, p) => p.SerializeAsV3(w));
// specification extensions
writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi3_0);
writer.WriteEndObject();
}
/// <summary>
/// Serialize <see cref="OpenApiOperation"/> to Open Api v3.0.
/// </summary>
public void SerializeAsV3(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// tags
writer.WriteOptionalCollection(
OpenApiConstants.Tags,
Tags,
(w, t) =>
{
t.SerializeAsV2(w);
});
// summary
writer.WriteProperty(OpenApiConstants.Summary, Summary);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// externalDocs
writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, e) => e.SerializeAsV3(w));
// operationId
writer.WriteProperty(OpenApiConstants.OperationId, OperationId);
// parameters
writer.WriteOptionalCollection(OpenApiConstants.Parameters, Parameters, (w, p) => p.SerializeAsV3(w));
// requestBody
writer.WriteOptionalObject(OpenApiConstants.RequestBody, RequestBody, (w, r) => r.SerializeAsV3(w));
// responses
writer.WriteRequiredObject(OpenApiConstants.Responses, Responses, (w, r) => r.SerializeAsV3(w));
// callbacks
writer.WriteOptionalMap(OpenApiConstants.Callbacks, Callbacks, (w, c) => c.SerializeAsV3(w));
// deprecated
writer.WriteProperty(OpenApiConstants.Deprecated, Deprecated, false);
// security
writer.WriteOptionalCollection(OpenApiConstants.Security, Security, (w, s) => s.SerializeAsV3(w));
// servers
writer.WriteOptionalCollection(OpenApiConstants.Servers, Servers, (w, s) => s.SerializeAsV3(w));
// specification extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
private void WriteInternal(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull("writer");
}
// { for json, empty for YAML
writer.WriteStartObject();
// summary
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocSummary, Summary);
// description
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocDescription, Description);
// get
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocGet, Get);
// put
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocPut, Put);
// post
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocPost, Post);
// delete
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocDelete, Delete);
// options
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocOptions, Options);
// head
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocHead, Head);
// patch
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocPatch, Patch);
// trace
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocTrace, Trace);
// servers
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocServers, Servers);
// parameters
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocParameters, Parameters);
// specification extensions
writer.WriteDictionary(Extensions);
// } for json, empty for YAML
writer.WriteEndObject();
}
/// <summary>
/// Write Open API operation object.
/// </summary>
/// <param name="writer">The Open API Writer.</param>
public virtual void Write(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull("writer");
}
// { for json, empty for YAML
writer.WriteStartObject();
// summary
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocSummary, Summary);
// tags
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocTags, Tags);
// description
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocDescription, Description);
// externalDocs
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocExternalDocs, ExternalDocs);
// operationId
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocOperationId, OperationId);
// parameters
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocParameters, Parameters);
// requestBody
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocRequestBody, RequestBody);
// responses
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocResponses, Responses);
// callbacks
writer.WriteOptionalDictionary(OpenApiConstants.OpenApiDocCallbacks, Callbacks);
// deprecated
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocDeprecated, Deprecated);
// security
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocSecurity, Security);
// servers
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocServers, Servers);
// specification extensions
writer.WriteDictionary(Extensions);
// } for json, empty for YAML
writer.WriteEndObject();
}
/// <summary>
/// Serialize <see cref="OpenApiDocument"/> to Open Api v2.0.
/// </summary>
public void SerializeAsV2(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// swagger
writer.WriteProperty(OpenApiConstants.Swagger, "2.0");
// info
writer.WriteRequiredObject(OpenApiConstants.Info, Info, (w, i) => i.SerializeAsV2(w));
// host, basePath, schemes, consumes, produces
WriteHostInfoV2(writer, Servers);
// paths
writer.WriteRequiredObject(OpenApiConstants.Paths, Paths, (w, p) => p.SerializeAsV2(w));
// definitions
writer.WriteOptionalMap(OpenApiConstants.Definitions, Components?.Schemas, (w, s) => s.SerializeAsV2WithoutReference(w));
// parameters
writer.WriteOptionalMap(OpenApiConstants.Parameters, Components?.Parameters, (w, p) => p.SerializeAsV2WithoutReference(w));
// responses
writer.WriteOptionalMap(OpenApiConstants.Responses, Components?.Responses, (w, r) => r.SerializeAsV2WithoutReference(w));
// securityDefinitions
writer.WriteOptionalMap(OpenApiConstants.SecurityDefinitions, Components?.SecuritySchemes, (w, s) => s.SerializeAsV2WithoutReference(w));
// security
writer.WriteOptionalCollection(
OpenApiConstants.Security,
SecurityRequirements,
(w, s) => s.SerializeAsV2(w));
// tags
writer.WriteOptionalCollection(OpenApiConstants.Tags, Tags, (w, t) => t.SerializeAsV2WithoutReference(w));
// externalDocs
writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, e) => e.SerializeAsV2(w));
// extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
/// <summary>
/// Serialize inline PathItem in OpenAPI V2
/// </summary>
/// <param name="writer"></param>
public void SerializeAsV2WithoutReference(IOpenApiWriter writer)
{
writer.WriteStartObject();
// operations except "trace"
foreach (var operation in Operations)
{
if (operation.Key != OperationType.Trace)
{
writer.WriteOptionalObject(
operation.Key.GetDisplayName(),
operation.Value,
(w, o) => o.SerializeAsV2(w));
}
}
// parameters
writer.WriteOptionalCollection(OpenApiConstants.Parameters, Parameters, (w, p) => p.SerializeAsV2(w));
// write "summary" as extensions
writer.WriteProperty(OpenApiConstants.ExtensionFieldNamePrefix + OpenApiConstants.Summary, Summary);
// write "description" as extensions
writer.WriteProperty(
OpenApiConstants.ExtensionFieldNamePrefix + OpenApiConstants.Description,
Description);
// specification extensions
writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi2_0);
writer.WriteEndObject();
}
/// <summary>
/// Write Open API document to the given writer.
/// </summary>
/// <param name="writer">The writer.</param>
public virtual void Write(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull("writer");
}
// { for json, empty for YAML
writer.WriteStartObject();
// openapi:3.0.0
writer.WriteRequiredProperty(OpenApiConstants.OpenApiDocOpenApi, OpenApi.ToString());
// info
writer.WriteRequiredObject(OpenApiConstants.OpenApiDocInfo, Info);
// servers
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocServers, Servers);
// paths
writer.WriteRequiredObject(OpenApiConstants.OpenApiDocPaths, Paths);
// components
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocComponents, Components);
// security
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocSecurity, Security);
// tags
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocTags, Tags);
// external docs
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocExternalDocs, ExternalDoc);
// specification extensions
writer.WriteDictionary(Extensions);
// } for json, empty for YAML
writer.WriteEndObject();
// flush
writer.Flush();
}
/// <summary>
/// Serialize <see cref="OpenApiDocument"/> to the latest patch of OpenAPI object V3.0.
/// </summary>
public void SerializeAsV3(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// openapi
writer.WriteProperty(OpenApiConstants.OpenApi, "3.0.1");
// info
writer.WriteRequiredObject(OpenApiConstants.Info, Info, (w, i) => i.SerializeAsV3(w));
// servers
writer.WriteOptionalCollection(OpenApiConstants.Servers, Servers, (w, s) => s.SerializeAsV3(w));
// paths
writer.WriteRequiredObject(OpenApiConstants.Paths, Paths, (w, p) => p.SerializeAsV3(w));
// components
writer.WriteOptionalObject(OpenApiConstants.Components, Components, (w, c) => c.SerializeAsV3(w));
// security
writer.WriteOptionalCollection(
OpenApiConstants.Security,
SecurityRequirements,
(w, s) => s.SerializeAsV3(w));
// tags
writer.WriteOptionalCollection(OpenApiConstants.Tags, Tags, (w, t) => t.SerializeAsV3WithoutReference(w));
// external docs
writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, e) => e.SerializeAsV3(w));
// extensions
writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi3_0);
writer.WriteEndObject();
}
private static void WriteHostInfoV2(IOpenApiWriter writer, IList <OpenApiServer> servers)
{
if (servers == null || !servers.Any())
{
return;
}
// Arbitrarily choose the first server given that V2 only allows
// one host, port, and base path.
var firstServer = servers.First();
// Divide the URL in the Url property into host and basePath required in OpenAPI V2
// The Url property cannotcontain path templating to be valid for V2 serialization.
var firstServerUrl = new Uri(firstServer.Url);
// host
writer.WriteProperty(
OpenApiConstants.Host,
firstServerUrl.GetComponents(UriComponents.Host | UriComponents.Port, UriFormat.SafeUnescaped));
// basePath
if (firstServerUrl.AbsolutePath != "/")
{
writer.WriteProperty(OpenApiConstants.BasePath, firstServerUrl.AbsolutePath);
}
// Consider all schemes of the URLs in the server list that have the same
// host, port, and base path as the first server.
var schemes = servers.Select(
s =>
{
Uri.TryCreate(s.Url, UriKind.RelativeOrAbsolute, out var url);
return(url);
})
.Where(
u => Uri.Compare(
u,
firstServerUrl,
UriComponents.Host | UriComponents.Port | UriComponents.Path,
UriFormat.SafeUnescaped,
StringComparison.OrdinalIgnoreCase) ==
0)
.Select(u => u.Scheme)
.Distinct()
.ToList();
// schemes
writer.WriteOptionalCollection(OpenApiConstants.Schemes, schemes, (w, s) => w.WriteValue(s));
}
/// <summary>
/// Serialize to OpenAPI V3 document without using reference.
/// </summary>
public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
{
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
writer.WriteProperty(OpenApiConstants.Style, Style?.GetDisplayName());
// explode
writer.WriteProperty(OpenApiConstants.Explode, Explode, false);
// allowReserved
writer.WriteProperty(OpenApiConstants.AllowReserved, AllowReserved, false);
// schema
writer.WriteOptionalObject(OpenApiConstants.Schema, Schema, (w, s) => s.SerializeAsV3(w));
// example
writer.WriteOptionalObject(OpenApiConstants.Example, Example, (w, s) => w.WriteAny(s));
// examples
writer.WriteOptionalCollection(OpenApiConstants.Examples, Examples, (w, e) => e.SerializeAsV3(w));
// content
writer.WriteOptionalMap(OpenApiConstants.Content, Content, (w, c) => c.SerializeAsV3(w));
// extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
/// <summary>
/// Serialize <see cref="OpenApiServerVariable"/> to Open Api v3.0
/// </summary>
public void SerializeAsV3(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// default
writer.WriteProperty(OpenApiConstants.Default, Default);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// enums
writer.WriteOptionalCollection(OpenApiConstants.Enum, Enum, (w, s) => w.WriteValue(s));
// specification extensions
writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi3_0);
writer.WriteEndObject();
}
internal void WriteAsSchemaProperties(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
// format
writer.WriteProperty(OpenApiConstants.Format, Format);
// title
writer.WriteProperty(OpenApiConstants.Title, Title);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// default
writer.WriteOptionalObject(OpenApiConstants.Default, Default, (w, d) => w.WriteAny(d));
// multipleOf
writer.WriteProperty(OpenApiConstants.MultipleOf, MultipleOf);
// maximum
writer.WriteProperty(OpenApiConstants.Maximum, Maximum);
// exclusiveMaximum
writer.WriteProperty(OpenApiConstants.ExclusiveMaximum, ExclusiveMaximum);
// minimum
writer.WriteProperty(OpenApiConstants.Minimum, Minimum);
// exclusiveMinimum
writer.WriteProperty(OpenApiConstants.ExclusiveMinimum, ExclusiveMinimum);
// maxLength
writer.WriteProperty(OpenApiConstants.MaxLength, MaxLength);
// minLength
writer.WriteProperty(OpenApiConstants.MinLength, MinLength);
// pattern
writer.WriteProperty(OpenApiConstants.Pattern, Pattern);
// maxItems
writer.WriteProperty(OpenApiConstants.MaxItems, MaxItems);
// minItems
writer.WriteProperty(OpenApiConstants.MinItems, MinItems);
// uniqueItems
writer.WriteProperty(OpenApiConstants.UniqueItems, UniqueItems);
// maxProperties
writer.WriteProperty(OpenApiConstants.MaxProperties, MaxProperties);
// minProperties
writer.WriteProperty(OpenApiConstants.MinProperties, MinProperties);
// required
writer.WriteOptionalCollection(OpenApiConstants.Required, Required, (w, s) => w.WriteValue(s));
// enum
writer.WriteOptionalCollection(OpenApiConstants.Enum, Enum, (w, s) => w.WriteAny(s));
// type
writer.WriteProperty(OpenApiConstants.Type, Type);
// items
writer.WriteOptionalObject(OpenApiConstants.Items, Items, (w, s) => s.SerializeAsV2(w));
// allOf
writer.WriteOptionalCollection(OpenApiConstants.AllOf, AllOf, (w, s) => s.SerializeAsV2(w));
// properties
writer.WriteOptionalMap(OpenApiConstants.Properties, Properties, (w, s) => s.SerializeAsV2(w));
// additionalProperties
writer.WriteOptionalObject(
OpenApiConstants.AdditionalProperties,
AdditionalProperties,
(w, s) => s.SerializeAsV2(w));
// discriminator
writer.WriteProperty(OpenApiConstants.Discriminator, Discriminator?.PropertyName);
// readOnly
writer.WriteProperty(OpenApiConstants.ReadOnly, ReadOnly, false);
// xml
writer.WriteOptionalObject(OpenApiConstants.Xml, Xml, (w, s) => s.SerializeAsV2(w));
// externalDocs
writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, s) => s.SerializeAsV2(w));
// example
writer.WriteOptionalObject(OpenApiConstants.Example, Example, (w, e) => w.WriteAny(e));
// extensions
writer.WriteExtensions(Extensions);
}
/// <summary>
/// Serialize <see cref="OpenApiDocument"/> to OpenAPI object V2.0.
/// </summary>
public void SerializeAsV2(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// swagger
writer.WriteProperty(OpenApiConstants.Swagger, "2.0");
// info
writer.WriteRequiredObject(OpenApiConstants.Info, Info, (w, i) => i.SerializeAsV2(w));
// host, basePath, schemes, consumes, produces
WriteHostInfoV2(writer, Servers);
// paths
writer.WriteRequiredObject(OpenApiConstants.Paths, Paths, (w, p) => p.SerializeAsV2(w));
// Serialize each referenceable object as full object without reference if the reference in the object points to itself.
// If the reference exists but points to other objects, the object is serialized to just that reference.
// definitions
writer.WriteOptionalMap(
OpenApiConstants.Definitions,
Components?.Schemas,
(w, key, component) =>
{
if (component.Reference != null &&
component.Reference.Type == ReferenceType.Schema &&
component.Reference.Id == key)
{
component.SerializeAsV2WithoutReference(w);
}
else
{
component.SerializeAsV2(w);
}
});
// parameters
writer.WriteOptionalMap(
OpenApiConstants.Parameters,
Components?.Parameters,
(w, key, component) =>
{
if (component.Reference != null &&
component.Reference.Type == ReferenceType.Parameter &&
component.Reference.Id == key)
{
component.SerializeAsV2WithoutReference(w);
}
else
{
component.SerializeAsV2(w);
}
});
// responses
writer.WriteOptionalMap(
OpenApiConstants.Responses,
Components?.Responses,
(w, key, component) =>
{
if (component.Reference != null &&
component.Reference.Type == ReferenceType.Response &&
component.Reference.Id == key)
{
component.SerializeAsV2WithoutReference(w);
}
else
{
component.SerializeAsV2(w);
}
});
// securityDefinitions
writer.WriteOptionalMap(
OpenApiConstants.SecurityDefinitions,
Components?.SecuritySchemes,
(w, key, component) =>
{
if (component.Reference != null &&
component.Reference.Type == ReferenceType.SecurityScheme &&
component.Reference.Id == key)
{
component.SerializeAsV2WithoutReference(w);
}
else
{
component.SerializeAsV2(w);
}
});
// security
writer.WriteOptionalCollection(
OpenApiConstants.Security,
SecurityRequirements,
(w, s) => s.SerializeAsV2(w));
// tags
writer.WriteOptionalCollection(OpenApiConstants.Tags, Tags, (w, t) => t.SerializeAsV2WithoutReference(w));
// externalDocs
writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, e) => e.SerializeAsV2(w));
// extensions
writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi2_0);
writer.WriteEndObject();
}
/// <summary>
/// Serialize <see cref="OpenApiDocument"/> to OpenAPI object V2.0.
/// </summary>
public void SerializeAsV2(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// swagger
writer.WriteProperty(OpenApiConstants.Swagger, "2.0");
// info
writer.WriteRequiredObject(OpenApiConstants.Info, Info, (w, i) => i.SerializeAsV2(w));
// host, basePath, schemes, consumes, produces
WriteHostInfoV2(writer, Servers);
// paths
writer.WriteRequiredObject(OpenApiConstants.Paths, Paths, (w, p) => p.SerializeAsV2(w));
// If references have been inlined we don't need the to render the components section
// however if they have cycles, then we will need a component rendered
if (writer.GetSettings().ReferenceInline != ReferenceInlineSetting.DoNotInlineReferences)
{
var loops = writer.GetSettings().LoopDetector.Loops;
if (loops.TryGetValue(typeof(OpenApiSchema), out List <object> schemas))
{
var openApiSchemas = schemas.Cast <OpenApiSchema>().Distinct().ToList()
.ToDictionary <OpenApiSchema, string>(k => k.Reference.Id);
foreach (var schema in openApiSchemas.Values.ToList())
{
FindSchemaReferences.ResolveSchemas(Components, openApiSchemas);
}
writer.WriteOptionalMap(
OpenApiConstants.Definitions,
openApiSchemas,
(w, key, component) =>
{
component.SerializeAsV2WithoutReference(w);
});
}
}
else
{
// Serialize each referenceable object as full object without reference if the reference in the object points to itself.
// If the reference exists but points to other objects, the object is serialized to just that reference.
// definitions
writer.WriteOptionalMap(
OpenApiConstants.Definitions,
Components?.Schemas,
(w, key, component) =>
{
if (component.Reference != null &&
component.Reference.Type == ReferenceType.Schema &&
component.Reference.Id == key)
{
component.SerializeAsV2WithoutReference(w);
}
else
{
component.SerializeAsV2(w);
}
});
}
// parameters
writer.WriteOptionalMap(
OpenApiConstants.Parameters,
Components?.Parameters,
(w, key, component) =>
{
if (component.Reference != null &&
component.Reference.Type == ReferenceType.Parameter &&
component.Reference.Id == key)
{
component.SerializeAsV2WithoutReference(w);
}
else
{
component.SerializeAsV2(w);
}
});
// responses
writer.WriteOptionalMap(
OpenApiConstants.Responses,
Components?.Responses,
(w, key, component) =>
{
if (component.Reference != null &&
component.Reference.Type == ReferenceType.Response &&
component.Reference.Id == key)
{
component.SerializeAsV2WithoutReference(w);
}
else
{
component.SerializeAsV2(w);
}
});
// securityDefinitions
writer.WriteOptionalMap(
OpenApiConstants.SecurityDefinitions,
Components?.SecuritySchemes,
(w, key, component) =>
{
if (component.Reference != null &&
component.Reference.Type == ReferenceType.SecurityScheme &&
component.Reference.Id == key)
{
component.SerializeAsV2WithoutReference(w);
}
else
{
component.SerializeAsV2(w);
}
});
// security
writer.WriteOptionalCollection(
OpenApiConstants.Security,
SecurityRequirements,
(w, s) => s.SerializeAsV2(w));
// tags
writer.WriteOptionalCollection(OpenApiConstants.Tags, Tags, (w, t) => t.SerializeAsV2WithoutReference(w));
// externalDocs
writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, e) => e.SerializeAsV2(w));
// extensions
writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi2_0);
writer.WriteEndObject();
}
private void WriteInternal(IOpenApiWriter writer)
{
Debug.Assert(writer != null);
// { for json, empty for YAML
writer.WriteStartObject();
// type
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocType, Type);
// title
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocTitle, Title);
// multipleOf
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocMultipleOf, MultipleOf);
// Pattern
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocPattern, Pattern);
// MaxItems
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocMaxItems, MaxItems);
// MinItems
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocMinItems, MinItems);
// UniqueItems
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocUniqueItems, UniqueItems);
// MaxProperties
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocMaxProperties, MaxProperties);
// MinProperties
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocMinProperties, MinProperties);
// Required
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocRequired, Required);
// enum
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocEnum, Enum);
// AllOf
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocAllOf, AllOf);
// OneOf
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocOneOf, OneOf);
// AnyOf
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocAnyOf, AnyOf);
// Not
writer.WriteOptionalCollection(OpenApiConstants.OpenApiDocNot, Not);
// Items
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocItems, Items);
// Properties
writer.WriteOptionalDictionary(OpenApiConstants.OpenApiDocProperties, Properties);
// AdditionalProperties
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocAdditionalProperties, AdditionalProperties);
// Description
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocDescription, Description);
// Format
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocFormat, Format);
// Maximum
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocMaximum, Maximum);
// exclusiveMaximum
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocExclusiveMaximum, ExclusiveMaximum);
// Minimum
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocMinimum, Minimum);
// exclusiveMinimum
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocExclusiveMinimum, ExclusiveMinimum);
// MaxLength
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocMaxLength, MaxLength);
// MaxLength
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocMinLength, MinLength);
// Default
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocDefault, Default);
// nullable
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocNullable, Nullable);
// Discriminator
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocDiscriminator, Discriminator);
// ReadOnly
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocReadOnly, ReadOnly);
// WriteOnly
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocWriteOnly, WriteOnly);
// XML
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocXml, Xml);
// ExternalDocs
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocExternalDocs, ExternalDocs);
// Example
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocExample, Example);
// Deprecated
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocDeprecated, Deprecated);
// specification extensions
writer.WriteDictionary(Extensions);
// } for json, empty for YAML
writer.WriteEndObject();
}
internal void WriteAsSchemaProperties(
IOpenApiWriter writer,
IList <string> parentRequiredProperties,
string propertyName)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
// format
writer.WriteProperty(OpenApiConstants.Format, Format);
// title
writer.WriteProperty(OpenApiConstants.Title, Title);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// default
writer.WriteOptionalObject(OpenApiConstants.Default, Default, (w, d) => w.WriteAny(d));
// multipleOf
writer.WriteProperty(OpenApiConstants.MultipleOf, MultipleOf);
// maximum
writer.WriteProperty(OpenApiConstants.Maximum, Maximum);
// exclusiveMaximum
writer.WriteProperty(OpenApiConstants.ExclusiveMaximum, ExclusiveMaximum);
// minimum
writer.WriteProperty(OpenApiConstants.Minimum, Minimum);
// exclusiveMinimum
writer.WriteProperty(OpenApiConstants.ExclusiveMinimum, ExclusiveMinimum);
// maxLength
writer.WriteProperty(OpenApiConstants.MaxLength, MaxLength);
// minLength
writer.WriteProperty(OpenApiConstants.MinLength, MinLength);
// pattern
writer.WriteProperty(OpenApiConstants.Pattern, Pattern);
// maxItems
writer.WriteProperty(OpenApiConstants.MaxItems, MaxItems);
// minItems
writer.WriteProperty(OpenApiConstants.MinItems, MinItems);
// uniqueItems
writer.WriteProperty(OpenApiConstants.UniqueItems, UniqueItems);
// maxProperties
writer.WriteProperty(OpenApiConstants.MaxProperties, MaxProperties);
// minProperties
writer.WriteProperty(OpenApiConstants.MinProperties, MinProperties);
// required
writer.WriteOptionalCollection(OpenApiConstants.Required, Required, (w, s) => w.WriteValue(s));
// enum
writer.WriteOptionalCollection(OpenApiConstants.Enum, Enum, (w, s) => w.WriteAny(s));
// type
writer.WriteProperty(OpenApiConstants.Type, Type);
// items
writer.WriteOptionalObject(OpenApiConstants.Items, Items, (w, s) => s.SerializeAsV2(w));
// allOf
writer.WriteOptionalCollection(OpenApiConstants.AllOf, AllOf, (w, s) => s.SerializeAsV2(w));
// properties
writer.WriteOptionalMap(OpenApiConstants.Properties, Properties, (w, key, s) =>
s.SerializeAsV2(w, Required, key));
// additionalProperties
writer.WriteOptionalObject(
OpenApiConstants.AdditionalProperties,
AdditionalProperties,
(w, s) => s.SerializeAsV2(w));
// discriminator
writer.WriteProperty(OpenApiConstants.Discriminator, Discriminator?.PropertyName);
// readOnly
// In V2 schema if a property is part of required properties of parent schema,
// it cannot be marked as readonly.
if (!parentRequiredProperties.Contains(propertyName))
{
writer.WriteProperty(name: OpenApiConstants.ReadOnly, value: ReadOnly, defaultValue: false);
}
// xml
writer.WriteOptionalObject(OpenApiConstants.Xml, Xml, (w, s) => s.SerializeAsV2(w));
// externalDocs
writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, s) => s.SerializeAsV2(w));
// example
writer.WriteOptionalObject(OpenApiConstants.Example, Example, (w, e) => w.WriteAny(e));
// extensions
writer.WriteExtensions(Extensions);
}
internal void WriteAsItemsProperties(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
// type
writer.WriteProperty(OpenApiConstants.Type, Type);
// format
writer.WriteProperty(OpenApiConstants.Format, Format);
// items
writer.WriteOptionalObject(OpenApiConstants.Items, Items, (w, s) => s.SerializeAsV2(w));
// collectionFormat
// We need information from style in parameter to populate this.
// The best effort we can make is to pull this information from the first parameter
// that leverages this schema. However, that in itself may not be as simple
// as the schema directly under parameter might be referencing one in the Components,
// so we will need to do a full scan of the object before we can write the value for
// this property. This is not supported yet, so we will skip this property at the moment.
// default
writer.WriteOptionalObject(OpenApiConstants.Default, Default, (w, d) => w.WriteAny(d));
// maximum
writer.WriteProperty(OpenApiConstants.Maximum, Maximum);
// exclusiveMaximum
writer.WriteProperty(OpenApiConstants.ExclusiveMaximum, ExclusiveMaximum);
// minimum
writer.WriteProperty(OpenApiConstants.Minimum, Minimum);
// exclusiveMinimum
writer.WriteProperty(OpenApiConstants.ExclusiveMinimum, ExclusiveMinimum);
// maxLength
writer.WriteProperty(OpenApiConstants.MaxLength, MaxLength);
// minLength
writer.WriteProperty(OpenApiConstants.MinLength, MinLength);
// pattern
writer.WriteProperty(OpenApiConstants.Pattern, Pattern);
// maxItems
writer.WriteProperty(OpenApiConstants.MaxItems, MaxItems);
// minItems
writer.WriteProperty(OpenApiConstants.MinItems, MinItems);
// enum
writer.WriteOptionalCollection(OpenApiConstants.Enum, Enum, (w, s) => w.WriteAny(s));
// multipleOf
writer.WriteProperty(OpenApiConstants.MultipleOf, MultipleOf);
// extensions
writer.WriteExtensions(Extensions);
}
/// <summary>
/// Serialize to OpenAPI V3 document without using reference.
/// </summary>
public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
{
writer.WriteStartObject();
// title
writer.WriteProperty(OpenApiConstants.Title, Title);
// multipleOf
writer.WriteProperty(OpenApiConstants.MultipleOf, MultipleOf);
// maximum
writer.WriteProperty(OpenApiConstants.Maximum, Maximum);
// exclusiveMaximum
writer.WriteProperty(OpenApiConstants.ExclusiveMaximum, ExclusiveMaximum);
// minimum
writer.WriteProperty(OpenApiConstants.Minimum, Minimum);
// exclusiveMinimum
writer.WriteProperty(OpenApiConstants.ExclusiveMinimum, ExclusiveMinimum);
// maxLength
writer.WriteProperty(OpenApiConstants.MaxLength, MaxLength);
// minLength
writer.WriteProperty(OpenApiConstants.MinLength, MinLength);
// pattern
writer.WriteProperty(OpenApiConstants.Pattern, Pattern);
// maxItems
writer.WriteProperty(OpenApiConstants.MaxItems, MaxItems);
// minItems
writer.WriteProperty(OpenApiConstants.MinItems, MinItems);
// uniqueItems
writer.WriteProperty(OpenApiConstants.UniqueItems, UniqueItems);
// maxProperties
writer.WriteProperty(OpenApiConstants.MaxProperties, MaxProperties);
// minProperties
writer.WriteProperty(OpenApiConstants.MinProperties, MinProperties);
// required
writer.WriteOptionalCollection(OpenApiConstants.Required, Required, (w, s) => w.WriteValue(s));
// enum
writer.WriteOptionalCollection(OpenApiConstants.Enum, Enum, (nodeWriter, s) => nodeWriter.WriteAny(s));
// type
writer.WriteProperty(OpenApiConstants.Type, Type);
// allOf
writer.WriteOptionalCollection(OpenApiConstants.AllOf, AllOf, (w, s) => s.SerializeAsV3(w));
// anyOf
writer.WriteOptionalCollection(OpenApiConstants.AnyOf, AnyOf, (w, s) => s.SerializeAsV3(w));
// oneOf
writer.WriteOptionalCollection(OpenApiConstants.OneOf, OneOf, (w, s) => s.SerializeAsV3(w));
// not
writer.WriteOptionalObject(OpenApiConstants.Not, Not, (w, s) => s.SerializeAsV3(w));
// items
writer.WriteOptionalObject(OpenApiConstants.Items, Items, (w, s) => s.SerializeAsV3(w));
// properties
writer.WriteOptionalMap(OpenApiConstants.Properties, Properties, (w, s) => s.SerializeAsV3(w));
// additionalProperties
writer.WriteOptionalObject(
OpenApiConstants.AdditionalProperties,
AdditionalProperties,
(w, s) => s.SerializeAsV3(w));
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// format
writer.WriteProperty(OpenApiConstants.Format, Format);
// default
writer.WriteOptionalObject(OpenApiConstants.Default, Default, (w, d) => w.WriteAny(d));
// nullable
writer.WriteProperty(OpenApiConstants.Nullable, Nullable, false);
// discriminator
writer.WriteOptionalObject(OpenApiConstants.Discriminator, Discriminator, (w, s) => s.SerializeAsV3(w));
// readOnly
writer.WriteProperty(OpenApiConstants.ReadOnly, ReadOnly, false);
// writeOnly
writer.WriteProperty(OpenApiConstants.WriteOnly, WriteOnly, false);
// xml
writer.WriteOptionalObject(OpenApiConstants.Xml, Xml, (w, s) => s.SerializeAsV2(w));
// externalDocs
writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, s) => s.SerializeAsV3(w));
// example
writer.WriteOptionalObject(OpenApiConstants.Example, Example, (w, e) => w.WriteAny(e));
// deprecated
writer.WriteProperty(OpenApiConstants.Deprecated, Deprecated, false);
// extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
/// <summary>
/// Serialize <see cref="OpenApiOperation"/> to Open Api v2.0.
/// </summary>
public void SerializeAsV2(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// tags
writer.WriteOptionalCollection(
OpenApiConstants.Tags,
Tags,
(w, t) =>
{
t.SerializeAsV3(w);
});
// summary
writer.WriteProperty(OpenApiConstants.Summary, Summary);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// externalDocs
writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, e) => e.SerializeAsV2(w));
// operationId
writer.WriteProperty(OpenApiConstants.OperationId, OperationId);
IList <OpenApiParameter> parameters;
if (Parameters == null)
{
parameters = new List <OpenApiParameter>();
}
else
{
parameters = new List <OpenApiParameter>(Parameters);
}
if (RequestBody != null)
{
// consumes
writer.WritePropertyName(OpenApiConstants.Consumes);
writer.WriteStartArray();
var consumes = RequestBody.Content.Keys.Distinct().ToList();
foreach (var mediaType in consumes)
{
writer.WriteValue(mediaType);
}
writer.WriteEndArray();
// This is form data. We need to split the request body into multiple parameters.
if (consumes.Contains("application/x-www-form-urlencoded") ||
consumes.Contains("multipart/form-data"))
{
foreach (var property in RequestBody.Content.First().Value.Schema.Properties)
{
parameters.Add(
new OpenApiFormDataParameter
{
Description = property.Value.Description,
Name = property.Key,
Schema = property.Value,
Required = RequestBody.Content.First().Value.Schema.Required.Contains(property.Key)
});
}
}
else
{
var bodyParameter = new OpenApiBodyParameter
{
Description = RequestBody.Description,
// V2 spec actually allows the body to have custom name.
// Our library does not support this at the moment.
Name = "body",
Schema = RequestBody.Content.First().Value.Schema,
Required = RequestBody.Required
};
parameters.Add(bodyParameter);
}
}
if (Responses != null)
{
var produces = Responses.Where(r => r.Value.Content != null)
.SelectMany(r => r.Value.Content?.Keys)
.Distinct()
.ToList();
if (produces.Any())
{
// produces
writer.WritePropertyName(OpenApiConstants.Produces);
writer.WriteStartArray();
foreach (var mediaType in produces)
{
writer.WriteValue(mediaType);
}
writer.WriteEndArray();
}
}
// parameters
// Use the parameters created locally to include request body if exists.
writer.WriteOptionalCollection(OpenApiConstants.Parameters, parameters, (w, p) => p.SerializeAsV2(w));
// responses
writer.WriteRequiredObject(OpenApiConstants.Responses, Responses, (w, r) => r.SerializeAsV2(w));
// schemes
// All schemes in the Servers are extracted, regardless of whether the host matches
// the host defined in the outermost Swagger object. This is due to the
// inaccessibility of information for that host in the context of an inner object like this Operation.
if (Servers != null)
{
var schemes = Servers.Select(
s =>
{
Uri.TryCreate(s.Url, UriKind.RelativeOrAbsolute, out var url);
return(url?.Scheme);
})
.Where(s => s != null)
.Distinct()
.ToList();
writer.WriteOptionalCollection(OpenApiConstants.Schemes, schemes, (w, s) => w.WriteValue(s));
}
// deprecated
writer.WriteProperty(OpenApiConstants.Deprecated, Deprecated, false);
// security
writer.WriteOptionalCollection(OpenApiConstants.Security, Security, (w, s) => s.SerializeAsV2(w));
// specification extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
/// <summary>
/// Serialize <see cref="OpenApiOperation"/> to Open Api v2.0.
/// </summary>
public void SerializeAsV2(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// tags
writer.WriteOptionalCollection(
OpenApiConstants.Tags,
Tags,
(w, t) =>
{
t.SerializeAsV3(w);
});
// summary
writer.WriteProperty(OpenApiConstants.Summary, Summary);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// externalDocs
writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, e) => e.SerializeAsV2(w));
// operationId
writer.WriteProperty(OpenApiConstants.OperationId, OperationId);
IList <OpenApiParameter> parameters;
if (Parameters == null)
{
parameters = new List <OpenApiParameter>();
}
else
{
parameters = new List <OpenApiParameter>(Parameters);
}
if (RequestBody != null)
{
// consumes
writer.WritePropertyName(OpenApiConstants.Consumes);
writer.WriteStartArray();
var consumes = RequestBody.Content.Keys.Distinct().ToList();
foreach (var mediaType in consumes)
{
writer.WriteValue(mediaType);
}
writer.WriteEndArray();
// Create a parameter as BodyParameter type and add to Parameters.
// This type will be used to populate the In property as "body" when Parameters is serialized.
var bodyParameter = new BodyParameter
{
Description = RequestBody.Description,
Schema = RequestBody.Content.First().Value.Schema,
Format = new List <string>(consumes)
};
parameters.Add(bodyParameter);
}
if (Responses != null)
{
var produces = Responses.Where(r => r.Value.Content != null)
.SelectMany(r => r.Value.Content?.Keys)
.Distinct()
.ToList();
if (produces.Any())
{
// produces
writer.WritePropertyName(OpenApiConstants.Produces);
writer.WriteStartArray();
foreach (var mediaType in produces)
{
writer.WriteValue(mediaType);
}
writer.WriteEndArray();
}
}
// parameters
// Use the parameters created locally to include request body if exists.
writer.WriteOptionalCollection(OpenApiConstants.Parameters, parameters, (w, p) => p.SerializeAsV2(w));
// responses
writer.WriteRequiredObject(OpenApiConstants.Responses, Responses, (w, r) => r.SerializeAsV2(w));
// schemes
// All schemes in the Servers are extracted, regardless of whether the host matches
// the host defined in the outermost Swagger object. This is due to the
// inaccessibility of information for that host in the context of an inner object like this Operation.
if (Servers != null)
{
var schemes = Servers.Select(
s =>
{
Uri.TryCreate(s.Url, UriKind.RelativeOrAbsolute, out var url);
return(url?.Scheme);
})
.Where(s => s != null)
.Distinct()
.ToList();
writer.WriteOptionalCollection(OpenApiConstants.Schemes, schemes, (w, s) => w.WriteValue(s));
}
// deprecated
writer.WriteProperty(OpenApiConstants.Deprecated, Deprecated, false);
// security
writer.WriteOptionalCollection(OpenApiConstants.Security, Security, (w, s) => s.SerializeAsV2(w));
// specification extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}