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 IParameter CreateParameter(
ApiDescription apiDescription,
ApiParameterDescription apiParameterDescription,
ISchemaRegistry schemaRegistry)
{
// Try to retrieve additional metadata that's not provided by ApiExplorer
ParameterInfo parameterInfo = null;
PropertyInfo propertyInfo = null;
var customAttributes = Enumerable.Empty <object>();
if (apiParameterDescription.TryGetParameterInfo(apiDescription, out parameterInfo))
{
customAttributes = parameterInfo.GetCustomAttributes(true);
}
else if (apiParameterDescription.TryGetPropertyInfo(out propertyInfo))
{
customAttributes = propertyInfo.GetCustomAttributes(true);
}
var name = _settings.DescribeAllParametersInCamelCase
? apiParameterDescription.Name.ToCamelCase()
: apiParameterDescription.Name;
var location = ParameterLocationMap.ContainsKey(apiParameterDescription.Source)
? ParameterLocationMap[apiParameterDescription.Source]
: "query";
var schema = (apiParameterDescription.Type != null)
? schemaRegistry.GetOrRegister(apiParameterDescription.Type)
: null;
var isRequired = customAttributes.Any(attr =>
new[] { typeof(RequiredAttribute), typeof(BindRequiredAttribute) }.Contains(attr.GetType()));
var parameter = (location == "body")
? new BodyParameter {
Name = name, Schema = schema, Required = isRequired
}
: CreateNonBodyParameter(
name,
location,
schema,
schemaRegistry,
isRequired,
customAttributes,
parameterInfo);
var filterContext = new ParameterFilterContext(
apiParameterDescription,
schemaRegistry,
parameterInfo,
propertyInfo);
foreach (var filter in _settings.ParameterFilters)
{
filter.Apply(parameter, filterContext);
}
return(parameter);
}
private OpenApiParameter GenerateParameter(
ApiParameterDescription apiParameter,
SchemaRepository schemaRepository)
{
var name = _options.DescribeAllParametersInCamelCase
? apiParameter.Name.ToCamelCase()
: apiParameter.Name;
var location = (apiParameter.Source != null && ParameterLocationMap.ContainsKey(apiParameter.Source))
? ParameterLocationMap[apiParameter.Source]
: ParameterLocation.Query;
var isRequired = (apiParameter.IsFromPath()) ||
apiParameter.CustomAttributes().Any(attr => RequiredAttributeTypes.Contains(attr.GetType()));
var schema = (apiParameter.ModelMetadata != null)
? _schemaGenerator.GenerateSchema(apiParameter.ModelMetadata.ModelType, schemaRepository)
: new OpenApiSchema {
Type = "string"
};
// If it's NOT a reference schema, apply contextual metadata (i.e. from custom attributes)
if (schema.Reference == null)
{
// Honor default value for optional action parameters
var parameterInfo = apiParameter.ParameterInfo();
if (parameterInfo != null && parameterInfo.HasDefaultValue)
{
schema.Default = OpenApiAnyFactory.TryCreateFor(schema, parameterInfo.DefaultValue, out IOpenApiAny openApiAny)
? openApiAny
: null;
}
schema.ApplyCustomAttributes(apiParameter.CustomAttributes());
}
var parameter = new OpenApiParameter
{
Name = name,
In = location,
Required = isRequired,
Schema = schema
};
var filterContext = new ParameterFilterContext(
apiParameter,
_schemaGenerator,
schemaRepository,
apiParameter.ParameterInfo(),
apiParameter.PropertyInfo());
foreach (var filter in _options.ParameterFilters)
{
filter.Apply(parameter, filterContext);
}
return(parameter);
}
private OpenApiParameter GenerateParameter(
ApiDescription apiDescription,
ApiParameterDescription apiParameter,
SchemaRepository schemaRepository)
{
apiParameter.GetAdditionalMetadata(
apiDescription,
out ParameterInfo parameterInfo,
out PropertyInfo propertyInfo,
out IEnumerable <object> parameterOrPropertyAttributes);
var name = _options.DescribeAllParametersInCamelCase
? apiParameter.Name.ToCamelCase()
: apiParameter.Name;
var location = ParameterLocationMap.ContainsKey(apiParameter.Source)
? ParameterLocationMap[apiParameter.Source]
: ParameterLocation.Query;
var isRequired = (apiParameter.IsFromPath()) ||
parameterOrPropertyAttributes.Any(attr => RequiredAttributeTypes.Contains(attr.GetType()));
var defaultValue = parameterInfo?.DefaultValue
?? parameterOrPropertyAttributes.OfType <DefaultValueAttribute>().FirstOrDefault()?.Value;
var schema = (apiParameter.ModelMetadata != null)
? _schemaGenerator.GenerateSchema(apiParameter.Type, schemaRepository)
: new OpenApiSchema {
Type = "string"
};
if (defaultValue != null && schema.Reference == null)
{
schema.Default = OpenApiAnyFactory.TryCreateFor(schema, defaultValue, out IOpenApiAny openApiAny)
? openApiAny
: null;
}
var parameter = new OpenApiParameter
{
Name = name,
In = location,
Required = isRequired,
Schema = schema
};
var filterContext = new ParameterFilterContext(apiParameter, _schemaGenerator, schemaRepository, parameterInfo, propertyInfo);
foreach (var filter in _options.ParameterFilters)
{
filter.Apply(parameter, filterContext);
}
return(parameter);
}
private OpenApiParameter GenerateParameter(
ApiParameterDescription apiParameter,
SchemaRepository schemaRepository)
{
var name = _options.DescribeAllParametersInCamelCase
? apiParameter.Name.ToCamelCase()
: apiParameter.Name;
var location = ParameterLocationMap.ContainsKey(apiParameter.Source)
? ParameterLocationMap[apiParameter.Source]
: ParameterLocation.Query;
var isRequired = (apiParameter.IsFromPath()) ||
apiParameter.CustomAttributes().Any(attr => RequiredAttributeTypes.Contains(attr.GetType()));
var schema = (apiParameter.ModelMetadata != null)
? _schemaGenerator.GenerateSchema(apiParameter.ModelMetadata.ModelType, schemaRepository)
: new OpenApiSchema {
Type = "string"
};
var defaultValue = apiParameter.CustomAttributes().OfType <DefaultValueAttribute>().FirstOrDefault()?.Value
?? apiParameter.ParameterInfo()?.DefaultValue;
// NOTE: Oddly, ParameterInfo.DefaultValue returns DBNull if not optional, hence the additional check below
if (schema.Reference == null && defaultValue != null && defaultValue != DBNull.Value)
{
schema.Default = OpenApiAnyFactory.TryCreateFor(schema, defaultValue, out IOpenApiAny openApiAny)
? openApiAny
: null;
}
var parameter = new OpenApiParameter
{
Name = name,
In = location,
Required = isRequired,
Schema = schema
};
var filterContext = new ParameterFilterContext(
apiParameter,
_schemaGenerator,
schemaRepository,
apiParameter.ParameterInfo(),
apiParameter.PropertyInfo());
foreach (var filter in _options.ParameterFilters)
{
filter.Apply(parameter, filterContext);
}
return(parameter);
}
public void Apply(OpenApiParameter parameter, ParameterFilterContext context)
{
if (context.PropertyInfo != null)
{
ApplyPropertyTags(parameter, context);
}
else if (context.ParameterInfo != null)
{
ApplyParamTags(parameter, context);
}
}
private IParameter CreateParameter(
ApiDescription apiDescription,
ApiParameterDescription apiParameterDescription,
ISchemaRegistry schemaRegistry)
{
// Try to retrieve additional metadata that's not directly provided by ApiExplorer
ParameterInfo parameterInfo = null;
PropertyInfo propertyInfo = null;
var customAttributes = Enumerable.Empty <object>();
if (apiParameterDescription.TryGetParameterInfo(apiDescription, out parameterInfo))
{
customAttributes = parameterInfo.GetCustomAttributes(true);
}
else if (apiParameterDescription.TryGetPropertyInfo(out propertyInfo))
{
customAttributes = propertyInfo.GetCustomAttributes(true);
}
var name = _options.DescribeAllParametersInCamelCase
? apiParameterDescription.Name.ToCamelCase()
: apiParameterDescription.Name;
var isRequired = customAttributes.Any(attr =>
new[] { typeof(RequiredAttribute), typeof(BindRequiredAttribute) }.Contains(attr.GetType()));
var parameter = (apiParameterDescription.Source == BindingSource.Body)
? CreateBodyParameter(
apiParameterDescription,
name,
isRequired,
schemaRegistry)
: CreateNonBodyParameter(
apiParameterDescription,
parameterInfo,
customAttributes,
name,
isRequired,
schemaRegistry);
var filterContext = new ParameterFilterContext(
apiParameterDescription,
schemaRegistry,
parameterInfo,
propertyInfo);
foreach (var filter in _options.ParameterFilters)
{
filter.Apply(parameter, filterContext);
}
return(parameter);
}
private OpenApiParameter GenerateParameter(
ApiDescription apiDescription,
ApiParameterDescription apiParameter,
ISchemaRegistry schemaRegistry)
{
apiParameter.GetAdditionalMetadata(
apiDescription,
out ParameterInfo parameterInfo,
out PropertyInfo propertyInfo,
out IEnumerable <object> parameterOrPropertyAttributes);
var name = _options.DescribeAllParametersInCamelCase
? apiParameter.Name.ToCamelCase()
: apiParameter.Name;
var location = ParameterLocationMap.ContainsKey(apiParameter.Source)
? ParameterLocationMap[apiParameter.Source]
: ParameterLocation.Query;
var isRequired = (apiParameter.IsFromPath()) ||
parameterOrPropertyAttributes.Any(attr => RequiredAttributeTypes.Contains(attr.GetType()));
var schema = (apiParameter.Type != null)
? schemaRegistry.GetOrRegister(apiParameter.Type)
: new OpenApiSchema {
Type = "string"
};
// If it corresponds to an optional action parameter, assign the default value
if (parameterInfo?.DefaultValue != null && schema.Reference == null)
{
schema.Default = OpenApiPrimitiveFactory.CreateFrom(parameterInfo.DefaultValue);
}
var parameter = new OpenApiParameter
{
Name = name,
In = location,
Required = isRequired,
Schema = schema
};
var filterContext = new ParameterFilterContext(apiParameter, schemaRegistry, parameterInfo, propertyInfo);
foreach (var filter in _options.ParameterFilters)
{
filter.Apply(parameter, filterContext);
}
return(parameter);
}
private OpenApiParameter GenerateParameter(
ApiParameterDescription apiParameter,
SchemaRepository schemaRepository)
{
var name = _options.DescribeAllParametersInCamelCase
? apiParameter.Name.ToCamelCase()
: apiParameter.Name;
var location = (apiParameter.Source != null && ParameterLocationMap.ContainsKey(apiParameter.Source))
? ParameterLocationMap[apiParameter.Source]
: ParameterLocation.Query;
var isRequired = (apiParameter.IsFromPath()) ||
apiParameter.CustomAttributes().Any(attr => RequiredAttributeTypes.Contains(attr.GetType()));
var schema = (apiParameter.ModelMetadata != null)
? _schemaGenerator.GenerateSchema(
apiParameter.ModelMetadata.ModelType,
schemaRepository,
apiParameter.PropertyInfo(),
apiParameter.ParameterInfo())
: new OpenApiSchema {
Type = "string"
};
var parameter = new OpenApiParameter
{
Name = name,
In = location,
Required = isRequired,
Schema = schema
};
var filterContext = new ParameterFilterContext(
apiParameter,
_schemaGenerator,
schemaRepository,
apiParameter.PropertyInfo(),
apiParameter.ParameterInfo());
foreach (var filter in _options.ParameterFilters)
{
filter.Apply(parameter, filterContext);
}
return(parameter);
}
private IParameter CreateParameter(
ApiDescription apiDescription,
ApiParameterDescription apiParameterDescription,
ISchemaRegistry schemaRegistry)
{
var name = _settings.DescribeAllParametersInCamelCase
? apiParameterDescription.Name.ToCamelCase()
: apiParameterDescription.Name;
var location = ParameterLocationMap.ContainsKey(apiParameterDescription.Source)
? ParameterLocationMap[apiParameterDescription.Source]
: "query";
var schema = (apiParameterDescription.Type != null)
? schemaRegistry.GetOrRegister(apiParameterDescription.Type)
: null;
var isRequired = apiParameterDescription.IsRequired();
var controllerParameterDescriptor = GetControllerParameterDescriptorOrNull(
apiDescription, apiParameterDescription);
var parameter = (location == "body")
? new BodyParameter {
Name = name, Schema = schema, Required = isRequired
}
: CreateNonBodyParameter(name, location, schema, isRequired, schemaRegistry);
var filterContext = new ParameterFilterContext(
apiParameterDescription,
controllerParameterDescriptor,
schemaRegistry);
foreach (var filter in _settings.ParameterFilters)
{
filter.Apply(parameter, filterContext);
}
return(parameter);
}
private void ApplyParamTags(OpenApiParameter parameter, ParameterFilterContext context)
{
if (!(context.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='{context.ParameterInfo.Name}']");
if (paramNode != null)
{
parameter.Description = XmlCommentsTextHelper.Humanize(paramNode.InnerXml);
var example = paramNode.GetAttribute("example", "");
if (string.IsNullOrEmpty(example))
{
return;
}
var exampleAsJson = (parameter.Schema?.ResolveType(context.SchemaRepository) == "string")
? $"\"{example}\""
: example;
parameter.Example = OpenApiAnyFactory.CreateFromJson(exampleAsJson);
}
}
