private OpenApiSchema CreatePrimitiveSchema(DataContract dataContract)
{
var schema = new OpenApiSchema
{
Type = dataContract.DataType.ToString().ToLower(CultureInfo.InvariantCulture),
Format = dataContract.DataFormat
};
// For backcompat only - EnumValues is obsolete
if (dataContract.EnumValues != null)
{
schema.Enum = dataContract.EnumValues
.Select(value => JsonSerializer.Serialize(value))
.Select(valueAsJson => OpenApiAnyFactory.CreateFromJson(valueAsJson))
.ToList();
return(schema);
}
if (dataContract.UnderlyingType.IsEnum)
{
schema.Enum = dataContract.UnderlyingType.GetEnumValues()
.Cast <object>()
.Distinct()
.Select(value => dataContract.JsonConverter(value))
.Select(valueAsJson => OpenApiAnyFactory.CreateFromJson(valueAsJson))
.ToList();
}
return(schema);
}
private void ApplyPropertyTags(OpenApiParameter parameter, ParameterFilterContext context)
{
var propertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(context.PropertyInfo);
var propertyNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{propertyMemberName}']");
if (propertyNode == null)
{
return;
}
var summaryNode = propertyNode.SelectSingleNode("summary");
if (summaryNode != null)
{
parameter.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
parameter.Schema.Description = null; // no need to duplicate
}
var exampleNode = propertyNode.SelectSingleNode("example");
if (exampleNode == null)
{
return;
}
var exampleAsJson = (parameter.Schema?.ResolveType(context.SchemaRepository) == "string")
? $"\"{exampleNode.ToString()}\""
: exampleNode.ToString();
parameter.Example = OpenApiAnyFactory.CreateFromJson(exampleAsJson);
}
private void ApplyPropertyTags(OpenApiRequestBody requestBody, RequestBodyFilterContext context, PropertyInfo propertyInfo)
{
var propertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(propertyInfo);
var propertyNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{propertyMemberName}']");
if (propertyNode == null)
{
return;
}
var summaryNode = propertyNode.SelectSingleNode("summary");
if (summaryNode != null)
{
requestBody.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
var exampleNode = propertyNode.SelectSingleNode("example");
if (exampleNode == null)
{
return;
}
foreach (var mediaType in requestBody.Content.Values)
{
var exampleAsJson = (mediaType.Schema?.ResolveType(context.SchemaRepository) == "string")
? $"\"{exampleNode.ToString()}\""
: exampleNode.ToString();
mediaType.Example = OpenApiAnyFactory.CreateFromJson(exampleAsJson);
}
}
private void ApplyMemberMetadata(OpenApiSchema schema, Type type, MemberInfo memberInfo)
{
if (_generatorOptions.UseAllOfToExtendReferenceSchemas && schema.Reference != null)
{
schema.AllOf = new[] { new OpenApiSchema {
Reference = schema.Reference
} };
schema.Reference = null;
}
if (schema.Reference == null)
{
var customAttributes = memberInfo.GetInlineAndMetadataAttributes();
schema.Nullable = type.IsReferenceOrNullableType();
var defaultValueAttribute = customAttributes.OfType <DefaultValueAttribute>().FirstOrDefault();
if (defaultValueAttribute != null)
{
var defaultAsJson = _serializerBehavior.Serialize(defaultValueAttribute.Value);
schema.Default = OpenApiAnyFactory.CreateFromJson(defaultAsJson); // TODO: address assumption that serializer returns JSON
}
var obsoleteAttribute = customAttributes.OfType <ObsoleteAttribute>().FirstOrDefault();
if (obsoleteAttribute != null)
{
schema.Deprecated = true;
}
schema.ApplyValidationAttributes(customAttributes);
}
}
private void ApplyMemberTags(OpenApiSchema schema, SchemaFilterContext context)
{
var fieldOrPropertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(context.MemberInfo);
var fieldOrPropertyNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{fieldOrPropertyMemberName}']");
if (fieldOrPropertyNode == null)
{
return;
}
var summaryNode = fieldOrPropertyNode.SelectSingleNode("summary");
if (summaryNode != null)
{
schema.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
var exampleNode = fieldOrPropertyNode.SelectSingleNode("example");
if (exampleNode != null)
{
var exampleAsJson = (schema.ResolveType(context.SchemaRepository) == "string")
? $"\"{exampleNode.InnerXml}\""
: exampleNode.InnerXml;
schema.Example = OpenApiAnyFactory.CreateFromJson(exampleAsJson);
}
}
private void ApplyParamTags(OpenApiParameter parameter, ParameterInfo parameterInfo)
{
if (!(parameterInfo.Member is MethodInfo methodInfo))
{
return;
}
// If method is from a constructed generic type, look for comments from the generic type method
var targetMethod = methodInfo.DeclaringType.IsConstructedGenericType
? methodInfo.GetUnderlyingGenericTypeMethod()
: methodInfo;
if (targetMethod == null)
{
return;
}
var methodMemberName = XmlCommentsNodeNameHelper.GetMemberNameForMethod(targetMethod);
var paramNode = _xmlNavigator.SelectSingleNode(
$"/doc/members/member[@name='{methodMemberName}']/param[@name='{parameterInfo.Name}']");
if (paramNode != null)
{
parameter.Description = XmlCommentsTextHelper.Humanize(paramNode.InnerXml);
var example = paramNode.GetAttribute("example", "");
if (!string.IsNullOrEmpty(example))
{
parameter.Example = OpenApiAnyFactory.CreateFromJson(example);
}
}
}
private OpenApiSchema GenerateSchemaForParameter(ParameterInfo parameterInfo, SchemaRepository schemaRepository)
{
var dataContract = GetDataContractFor(parameterInfo.ParameterType);
var schema = _generatorOptions.UseOneOfForPolymorphism && IsBaseTypeWithKnownTypesDefined(dataContract, out var knownTypesDataContracts)
? GeneratePolymorphicSchema(dataContract, schemaRepository, knownTypesDataContracts)
: GenerateConcreteSchema(dataContract, schemaRepository);
if (_generatorOptions.UseAllOfToExtendReferenceSchemas && schema.Reference != null)
{
schema.AllOf = new[] { new OpenApiSchema {
Reference = schema.Reference
} };
schema.Reference = null;
}
if (schema.Reference == null)
{
if (parameterInfo.HasDefaultValue)
{
var defaultAsJson = dataContract.JsonConverter(parameterInfo.DefaultValue);
schema.Default = OpenApiAnyFactory.CreateFromJson(defaultAsJson);
}
schema.ApplyValidationAttributes(parameterInfo.GetCustomAttributes());
ApplyFilters(schema, parameterInfo.ParameterType, schemaRepository, parameterInfo: parameterInfo);
}
return(schema);
}
private OpenApiSchema GenerateSchemaForMember(
MemberInfo memberInfo,
SchemaRepository schemaRepository,
DataProperty dataProperty = null)
{
var memberType = memberInfo.MemberType == MemberTypes.Field
? ((FieldInfo)memberInfo).FieldType
: ((PropertyInfo)memberInfo).PropertyType;
var dataContract = GetDataContractFor(memberType);
var schema = _generatorOptions.UseOneOfForPolymorphism && IsBaseTypeWithKnownTypesDefined(dataContract, out var knownTypesDataContracts)
? GeneratePolymorphicSchema(dataContract, schemaRepository, knownTypesDataContracts)
: GenerateConcreteSchema(dataContract, schemaRepository);
if (_generatorOptions.UseAllOfToExtendReferenceSchemas && schema.Reference != null)
{
schema.AllOf = new[] { new OpenApiSchema {
Reference = schema.Reference
} };
schema.Reference = null;
}
if (schema.Reference == null)
{
var customAttributes = memberInfo.GetInlineAndMetadataAttributes();
// Nullable, ReadOnly & WriteOnly are only relevant for Schema "properties" (i.e. where dataProperty is non-null)
if (dataProperty != null)
{
schema.Nullable = _generatorOptions.SupportNonNullableReferenceTypes
? dataProperty.IsNullable && !customAttributes.OfType <RequiredAttribute>().Any() && !memberInfo.IsNonNullableReferenceType()
: dataProperty.IsNullable && !customAttributes.OfType <RequiredAttribute>().Any();
schema.ReadOnly = dataProperty.IsReadOnly;
schema.WriteOnly = dataProperty.IsWriteOnly;
}
var defaultValueAttribute = customAttributes.OfType <DefaultValueAttribute>().FirstOrDefault();
if (defaultValueAttribute != null)
{
var defaultAsJson = dataContract.JsonConverter(defaultValueAttribute.Value);
schema.Default = OpenApiAnyFactory.CreateFromJson(defaultAsJson);
}
var obsoleteAttribute = customAttributes.OfType <ObsoleteAttribute>().FirstOrDefault();
if (obsoleteAttribute != null)
{
schema.Deprecated = true;
}
schema.ApplyValidationAttributes(customAttributes);
ApplyFilters(schema, memberType, schemaRepository, memberInfo: memberInfo);
}
return(schema);
}
private OpenApiSchema GenerateSchemaForParameter(
Type modelType,
SchemaRepository schemaRepository,
ParameterInfo parameterInfo,
ApiParameterRouteInfo routeInfo)
{
var dataContract = GetDataContractFor(modelType);
var schema = _generatorOptions.UseOneOfForPolymorphism && IsBaseTypeWithKnownTypesDefined(dataContract, out var knownTypesDataContracts)
? GeneratePolymorphicSchema(dataContract, schemaRepository, knownTypesDataContracts)
: GenerateConcreteSchema(dataContract, schemaRepository);
if (_generatorOptions.UseAllOfToExtendReferenceSchemas && schema.Reference != null)
{
schema.AllOf = new[] { new OpenApiSchema {
Reference = schema.Reference
} };
schema.Reference = null;
}
if (schema.Reference == null)
{
var customAttributes = parameterInfo.GetCustomAttributes();
var defaultValue = parameterInfo.HasDefaultValue
? parameterInfo.DefaultValue
: customAttributes.OfType <DefaultValueAttribute>().FirstOrDefault()?.Value;
if (defaultValue != null)
{
var defaultAsJson = dataContract.JsonConverter(defaultValue);
schema.Default = OpenApiAnyFactory.CreateFromJson(defaultAsJson);
}
schema.ApplyValidationAttributes(customAttributes);
if (routeInfo != null)
{
schema.ApplyRouteConstraints(routeInfo);
}
ApplyFilters(schema, modelType, schemaRepository, parameterInfo: parameterInfo);
}
return(schema);
}
private OpenApiSchema GeneratePrimitiveSchema(DataContract dataContract)
{
var schema = new OpenApiSchema
{
Type = dataContract.DataType.ToString().ToLower(CultureInfo.InvariantCulture),
Format = dataContract.DataFormat
};
if (dataContract.UnderlyingType.IsEnum)
{
schema.Enum = dataContract.UnderlyingType.GetEnumValues()
.Cast <object>()
.Distinct()
.Select(value => _serializerBehavior.Serialize(value))
.Select(json => OpenApiAnyFactory.CreateFromJson(json))
.ToList();
}
return(schema);
}
private void ApplyParamTags(OpenApiRequestBody requestBody, RequestBodyFilterContext context, ParameterInfo parameterInfo)
{
if (!(parameterInfo.Member is MethodInfo methodInfo))
{
return;
}
// If method is from a constructed generic type, look for comments from the generic type method
var targetMethod = methodInfo.DeclaringType.IsConstructedGenericType
? methodInfo.GetUnderlyingGenericTypeMethod()
: methodInfo;
if (targetMethod == null)
{
return;
}
var methodMemberName = XmlCommentsNodeNameHelper.GetMemberNameForMethod(targetMethod);
var paramNode = _xmlNavigator.SelectSingleNode(
$"/doc/members/member[@name='{methodMemberName}']/param[@name='{parameterInfo.Name}']");
if (paramNode != null)
{
requestBody.Description = XmlCommentsTextHelper.Humanize(paramNode.InnerXml);
var example = paramNode.GetAttribute("example", "");
if (string.IsNullOrEmpty(example))
{
return;
}
foreach (var mediaType in requestBody.Content.Values)
{
var exampleAsJson = (mediaType.Schema?.ResolveType(context.SchemaRepository) == "string")
? $"\"{example}\""
: example;
mediaType.Example = OpenApiAnyFactory.CreateFromJson(exampleAsJson);
}
}
}
private void ApplyParameterMetadata(OpenApiSchema schema, Type type, ParameterInfo parameterInfo)
{
if (_generatorOptions.UseAllOfToExtendReferenceSchemas && schema.Reference != null)
{
schema.AllOf = new[] { new OpenApiSchema {
Reference = schema.Reference
} };
schema.Reference = null;
}
if (schema.Reference == null)
{
schema.Nullable = type.IsReferenceOrNullableType();
if (parameterInfo.HasDefaultValue)
{
var defaultAsJson = _serializerBehavior.Serialize(parameterInfo.DefaultValue);
schema.Default = OpenApiAnyFactory.CreateFromJson(defaultAsJson);
}
schema.ApplyValidationAttributes(parameterInfo.GetCustomAttributes());
}
}
private void ApplyPropertyTags(OpenApiParameter parameter, PropertyInfo propertyInfo)
{
var propertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(propertyInfo);
var propertyNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{propertyMemberName}']");
if (propertyNode == null)
{
return;
}
var summaryNode = propertyNode.SelectSingleNode("summary");
if (summaryNode != null)
{
parameter.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
var exampleNode = propertyNode.SelectSingleNode("example");
if (exampleNode != null)
{
parameter.Example = OpenApiAnyFactory.CreateFromJson(exampleNode.InnerXml);
}
}