/// <summary>
/// Write Any object to the given writer.
/// </summary>
/// <param name="writer">The writer.</param>
public void Write(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull("writer");
}
// { for json, empty for YAML
writer.WriteStartObject();
// specification extensions
writer.WriteDictionary(Extensions);
// } for json, empty for YAML
writer.WriteEndObject();
}
public void Write(IOpenApiWriter writer, OpenApiSpecVersion specVersion)
{
NullGuard.NotNull(writer, nameof(writer))
.NotNull(specVersion, nameof(specVersion));
writer.WriteStartObject();
writer.WriteProperty(nameof(ErrorCode), ErrorCode.ToString());
if (string.IsNullOrWhiteSpace(ErrorType) == false)
{
writer.WriteProperty(nameof(ErrorType), ErrorType);
}
if (string.IsNullOrWhiteSpace(ErrorMessage) == false)
{
writer.WriteProperty(nameof(ErrorMessage), ErrorMessage);
}
writer.WriteEndObject();
}
/// <summary>
/// Serialize <see cref="OpenApiDiscriminator"/> to Open Api v3.0
/// </summary>
public void SerializeAsV3(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// propertyName
writer.WriteProperty(OpenApiConstants.PropertyName, PropertyName);
// mapping
writer.WriteOptionalMap(OpenApiConstants.Mapping, Mapping, (w, s) => w.WriteValue(s));
writer.WriteEndObject();
}
/// <summary>
/// Serialize to OpenAPI V3 document without using reference.
/// </summary>
public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
{
writer.WriteStartObject();
// type
writer.WriteProperty(OpenApiConstants.Type, Type.GetDisplayName());
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
switch (Type)
{
case SecuritySchemeType.ApiKey:
// These properties apply to apiKey type only.
// name
// in
writer.WriteProperty(OpenApiConstants.Name, Name);
writer.WriteProperty(OpenApiConstants.In, In.GetDisplayName());
break;
case SecuritySchemeType.Http:
// These properties apply to http type only.
// scheme
// bearerFormat
writer.WriteProperty(OpenApiConstants.Scheme, Scheme);
writer.WriteProperty(OpenApiConstants.BearerFormat, BearerFormat);
break;
case SecuritySchemeType.OAuth2:
// This property apply to oauth2 type only.
// flows
writer.WriteOptionalObject(OpenApiConstants.Flows, Flows, (w, o) => o.SerializeAsV3(w));
break;
case SecuritySchemeType.OpenIdConnect:
// This property apply to openIdConnect only.
// openIdConnectUrl
writer.WriteProperty(OpenApiConstants.OpenIdConnectUrl, OpenIdConnectUrl?.ToString());
break;
}
// extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
/// <summary>
/// Serialize to OpenAPI V3 document without using reference.
/// </summary>
public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
{
writer.WriteStartObject();
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// content
writer.WriteRequiredMap(OpenApiConstants.Content, Content, (w, c) => c.SerializeAsV3(w));
// required
writer.WriteProperty(OpenApiConstants.Required, Required, false);
// extensions
writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi3_0);
writer.WriteEndObject();
}
/// <summary>
/// Serialize to OpenAPI V3 document without using reference.
/// </summary>
public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
{
writer.WriteStartObject();
// name
writer.WriteProperty(OpenApiConstants.Name, Name);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// external docs
writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, e) => e.SerializeAsV3(w));
// extensions.
writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi3_0);
writer.WriteEndObject();
}
/// <summary>
/// Write an object with an action.
/// </summary>
/// <param name="writer">The writer.</param>
/// <param name="objectAction">The object action.</param>
public static void WriteObject(this IOpenApiWriter writer, Action objectAction)
{
if (writer == null)
{
throw Error.ArgumentNull("writer");
}
if (objectAction == null)
{
throw Error.ArgumentNull("valueAction");
}
writer.WriteStartObject();
objectAction();
writer.WriteEndObject();
}
/// <summary>
/// Serialize to Open Api v2.0
/// </summary>
public void SerializeAsV2(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
foreach (var item in this)
{
writer.WriteRequiredObject(item.Key, item.Value, (w, p) => p.SerializeAsV2(w));
}
writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi2_0);
writer.WriteEndObject();
}
public bool TryWriteValue(IOpenApiWriter writer, JSchema schema)
{
switch (schema.Type)
{
case JSchemaType.String:
writer.WriteValue("text");
return(true);
case JSchemaType.Number:
case JSchemaType.Integer:
writer.WriteValue(42);
return(true);
case JSchemaType.Boolean:
writer.WriteValue(true);
return(true);
case JSchemaType.None:
return(true);
case JSchemaType.Null:
writer.WriteNull();
return(true);
case null:
return(true);
case JSchemaType.Object:
writer.WriteStartObject();
foreach (var(propName, propSchema) in schema.Properties)
{
writer.WritePropertyName(propName);
TryWriteValue(writer, propSchema);
}
writer.WriteEndObject();
return(true);
case JSchemaType.Array:
return(false);
default:
throw new ArgumentOutOfRangeException();
}
}
/// <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();
}
private static void WriteDictionaryInternal <T>(this IOpenApiWriter writer, string name, IDictionary <string, T> elements)
{
CheckArgument(writer, name);
writer.WritePropertyName(name);
writer.WriteStartObject();
if (elements != null)
{
foreach (KeyValuePair <string, T> e in elements)
{
writer.WritePropertyName(e.Key);
writer.WriteValueInternal(e.Value);
}
}
writer.WriteEndObject();
}
/// <summary>
/// Write components object 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();
// schemas
writer.WriteOptionalDictionary(OpenApiConstants.OpenApiDocSchemas, Schemas);
// responses
writer.WriteOptionalDictionary(OpenApiConstants.OpenApiDocResponses, Responses);
// parameters
writer.WriteOptionalDictionary(OpenApiConstants.OpenApiDocParameters, Parameters);
// examples
writer.WriteOptionalDictionary(OpenApiConstants.OpenApiDocExamples, Examples);
// requestBodies
writer.WriteOptionalDictionary(OpenApiConstants.OpenApiDocRequestBodies, RequestBodies);
// headers
writer.WriteOptionalDictionary(OpenApiConstants.OpenApiDocHeaders, Headers);
// securitySchemes
writer.WriteOptionalDictionary(OpenApiConstants.OpenApiDocSecuritySchemes, SecuritySchemes);
// links
writer.WriteOptionalDictionary(OpenApiConstants.OpenApiDocLinks, Links);
// callbacks
writer.WriteOptionalDictionary(OpenApiConstants.OpenApiDocCallbacks, Callbacks);
// specification extensions
writer.WriteDictionary(Extensions);
// } for json, empty for YAML
writer.WriteEndObject();
}
/// <summary>
/// Serialize to OpenAPI V3 document without using reference.
/// </summary>
public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
{
writer.WriteStartObject();
// 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.WriteOptionalMap(OpenApiConstants.Examples, Examples, (w, e) => e.SerializeAsV3(w));
// content
writer.WriteOptionalMap(OpenApiConstants.Content, Content, (w, c) => c.SerializeAsV3(w));
// extensions
writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi3_0);
writer.WriteEndObject();
}
/// <summary>
/// Write the required Open API object/element.
/// </summary>
/// <typeparam name="T">The Open API element type. <see cref="IOpenApiElement"/></typeparam>
/// <param name="writer">The Open API writer.</param>
/// <param name="name">The property name.</param>
/// <param name="value">The property value.</param>
/// <param name="action">The proprety value writer action.</param>
public static void WriteRequiredObject <T>(
this IOpenApiWriter writer,
string name,
T value,
Action <IOpenApiWriter, T> action)
where T : IOpenApiElement
{
CheckArguments(writer, name, action);
writer.WritePropertyName(name);
if (value != null)
{
action(writer, value);
}
else
{
writer.WriteStartObject();
writer.WriteEndObject();
}
}
private void WriteInternal(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// url
writer.WriteProperty(OpenApiConstants.Url, Url?.OriginalString);
// extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
private void WriteInternal(IOpenApiWriter writer, OpenApiSpecVersion specVersion)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// name
writer.WriteProperty(OpenApiConstants.Name, Name);
// url
writer.WriteProperty(OpenApiConstants.Url, Url?.OriginalString);
// specification extensions
writer.WriteExtensions(Extensions, specVersion);
writer.WriteEndObject();
}
/// <summary>
/// Serialize <see cref="OpenApiComponents"/> to Open Api v3.0.
/// </summary>
public void SerializeAsV3(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// schemas
writer.WriteOptionalMap(OpenApiConstants.Schemas, Schemas, (w, s) => s.SerializeAsV3WithoutReference(w));
// responses
writer.WriteOptionalMap(OpenApiConstants.Responses, Responses, (w, r) => r.SerializeAsV3WithoutReference(w));
// parameters
writer.WriteOptionalMap(OpenApiConstants.Parameters, Parameters, (w, p) => p.SerializeAsV3WithoutReference(w));
// examples
writer.WriteOptionalMap(OpenApiConstants.Examples, Examples, (w, e) => e.SerializeAsV3WithoutReference(w));
// requestBodies
writer.WriteOptionalMap(OpenApiConstants.RequestBodies, RequestBodies, (w, r) => r.SerializeAsV3WithoutReference(w));
// headers
writer.WriteOptionalMap(OpenApiConstants.Headers, Headers, (w, h) => h.SerializeAsV3WithoutReference(w));
// securitySchemes
writer.WriteOptionalMap(OpenApiConstants.SecuritySchemes, SecuritySchemes, (w, s) => s.SerializeAsV3WithoutReference(w));
// links
writer.WriteOptionalMap(OpenApiConstants.Links, Links, (w, link) => link.SerializeAsV3WithoutReference(w));
// callbacks
writer.WriteOptionalMap(OpenApiConstants.Callbacks, Callbacks, (w, c) => c.SerializeAsV3WithoutReference(w));
// extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
/// <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();
}
/// <summary>
/// Serialize to OpenAPI V3 document without using reference.
/// </summary>
public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
{
writer.WriteStartObject();
// summary
writer.WriteProperty(OpenApiConstants.Summary, Summary);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// value
writer.WriteOptionalObject(OpenApiConstants.Value, Value, (w, v) => w.WriteAny(v));
// externalValue
writer.WriteProperty(OpenApiConstants.ExternalValue, ExternalValue);
// extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
/// <inheritdoc />
public void Write(IOpenApiWriter writer, OpenApiSpecVersion specVersion)
{
if (writer == null)
{
throw new ArgumentNullException(nameof(writer));
}
writer.WriteStartObject();
if (!string.IsNullOrEmpty(NextLinkName))
{
writer.WriteProperty(nameof(NextLinkName).ToFirstCharacterLowerCase(), NextLinkName);
}
if (!string.IsNullOrEmpty(OperationName))
{
writer.WriteProperty(nameof(OperationName).ToFirstCharacterLowerCase(), OperationName);
}
writer.WriteProperty(nameof(ItemName).ToFirstCharacterLowerCase(), ItemName);
writer.WriteEndObject();
}
/// <summary>
/// Serialize to OpenAPI V3 document without using reference.
/// </summary>
public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
{
writer.WriteStartObject();
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// headers
writer.WriteOptionalMap(OpenApiConstants.Headers, Headers, (w, h) => h.SerializeAsV3(w));
// content
writer.WriteOptionalMap(OpenApiConstants.Content, Content, (w, c) => c.SerializeAsV3(w));
// links
writer.WriteOptionalMap(OpenApiConstants.Links, Links, (w, l) => l.SerializeAsV3(w));
// extension
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
public bool TryWriteValue(IOpenApiWriter writer, JSchema schema)
{
if (!schema.IsObject())
{
return(false);
}
writer.WriteStartObject();
using (DepthCounter.Enter())
{
if (DepthCounter.CanEnter)
{
WriteProperties(writer, schema);
}
}
writer.WriteEndObject();
return(true);
}
private static void WriteObject(this IOpenApiWriter writer, OpenApiObject entity)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
if (entity == null)
{
throw Error.ArgumentNull(nameof(entity));
}
writer.WriteStartObject();
foreach (var item in entity)
{
writer.WritePropertyName(item.Key);
writer.WriteAny(item.Value);
}
writer.WriteEndObject();
}
/// <summary>
/// Write Open API External Documentation 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();
// description
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocDescription, Description);
// url
writer.WriteRequiredProperty(OpenApiConstants.OpenApiDocUrl, Url?.OriginalString);
// specification extensions
writer.WriteDictionary(Extensions);
// } for json, empty for YAML
writer.WriteEndObject();
}
private void WriteInternal(IOpenApiWriter writer)
{
// { for json, empty for YAML
writer.WriteStartObject();
// summary
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocSummary, Summary);
// description
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocDescription, Description);
// value
writer.WriteOptionalObject(OpenApiConstants.OpenApiDocValue, Value);
// externalValue
writer.WriteOptionalProperty(OpenApiConstants.OpenApiDocExternalValue, ExternalValue?.OriginalString);
// specification extensions
writer.WriteDictionary(Extensions);
// } for json, empty for YAML
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();
}
private void WriteInternal(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// name
writer.WriteProperty(OpenApiConstants.Name, Name);
// url
writer.WriteProperty(OpenApiConstants.Url, Url?.OriginalString);
// email
writer.WriteProperty(OpenApiConstants.Email, Email);
// extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
/// <summary>
/// Serialize <see cref="OpenApiServer"/> to Open Api v3.0
/// </summary>
public void SerializeAsV3(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(writer));
}
writer.WriteStartObject();
// url
writer.WriteProperty(OpenApiConstants.Url, Url);
// description
writer.WriteProperty(OpenApiConstants.Description, Description);
// variables
writer.WriteOptionalMap(OpenApiConstants.Variables, Variables, (w, v) => v.SerializeAsV3(w));
// specification extensions
writer.WriteExtensions(Extensions);
writer.WriteEndObject();
}
/// <summary>
/// Serialize <see cref="OpenApiPathItem"/> to Open Api v2.0
/// </summary>
public void SerializeAsV2(IOpenApiWriter writer)
{
if (writer == null)
{
throw Error.ArgumentNull(nameof(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);
writer.WriteEndObject();
}
/// <summary>
/// Serialize to OpenAPI V2 document without using reference.
/// </summary>
public void SerializeAsV2WithoutReference(IOpenApiWriter writer)
{
writer.WriteStartObject();
// 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
Schema?.WriteAsItemsProperties(writer);
// example
writer.WriteOptionalObject(OpenApiConstants.Example, Example, (w, s) => w.WriteAny(s));
// extensions
writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi2_0);
writer.WriteEndObject();
}