private void ApplyFieldOrPropertyTags(OpenApiSchema schema, MemberInfo fieldOrPropertyInfo)
{
var fieldOrPropertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(fieldOrPropertyInfo);
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 exampleString = XmlCommentsTextHelper.Humanize(exampleNode.InnerXml);
if (fieldOrPropertyInfo is FieldInfo fieldInfo)
{
schema.Example = ConvertToOpenApiType(fieldInfo.FieldType, schema, exampleString);
}
else if (fieldOrPropertyInfo is PropertyInfo propertyInfo)
{
schema.Example = ConvertToOpenApiType(propertyInfo.PropertyType, schema, exampleString);
}
}
}
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)
{
var exampleString = XmlCommentsTextHelper.Humanize(exampleNode.InnerXml);
parameter.Example = ConvertToOpenApiType(propertyInfo.PropertyType, parameter.Schema, exampleString);
}
}
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
// Collect (unique) controller names and types in a dictionary
var controllerNamesAndTypes = context.ApiDescriptions
.Select(apiDesc => apiDesc.ActionDescriptor as ControllerActionDescriptor)
.SkipWhile(actionDesc => actionDesc == null)
.GroupBy(actionDesc => actionDesc.ControllerName)
.Select(group => new KeyValuePair <string, Type>(group.Key, group.First().ControllerTypeInfo.AsType()));
foreach (var nameAndType in controllerNamesAndTypes)
{
var memberName = XmlCommentsNodeNameHelper.GetMemberNameForType(nameAndType.Value);
var typeNode = _xmlNavigator.SelectSingleNode(string.Format(MemberXPath, memberName));
if (typeNode != null)
{
var summaryNode = typeNode.SelectSingleNode(SummaryTag);
if (summaryNode != null)
{
if (swaggerDoc.Tags == null)
{
swaggerDoc.Tags = new List <OpenApiTag>();
}
swaggerDoc.Tags.Add(new OpenApiTag
{
Name = nameAndType.Key,
Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml)
});
}
}
}
}
private void TryApplyMemberComments(OpenApiSchema schema, MemberInfo memberInfo)
{
var memberNodeName = XmlCommentsNodeNameHelper.GetNodeNameForMember(memberInfo);
var memberNode = _xmlNavigator.SelectSingleNode(string.Format(NodeXPath, memberNodeName));
if (memberNode == null)
{
return;
}
var summaryNode = memberNode.SelectSingleNode(SummaryTag);
if (summaryNode != null)
{
schema.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
var exampleNode = memberNode.SelectSingleNode(ExampleXPath);
if (exampleNode != null)
{
var exampleString = XmlCommentsTextHelper.Humanize(exampleNode.InnerXml);
var memberType = (memberInfo.MemberType & MemberTypes.Field) != 0 ? ((FieldInfo)memberInfo).FieldType : ((PropertyInfo)memberInfo).PropertyType;
schema.Example = ConvertToOpenApiType(memberType, schema, exampleString);
}
}
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 ApplyControllerTags(OpenApiOperation operation, Type controllerType)
{
var typeMemberName = XmlCommentsNodeNameHelper.GetMemberNameForType(controllerType);
var responseNodes = _xmlNavigator.Select($"/doc/members/member[@name='{typeMemberName}']/response");
ApplyResponseTags(operation, responseNodes);
}
private void ApplyMethodTags(OpenApiOperation operation, MethodInfo methodInfo)
{
var methodMemberName = XmlCommentsNodeNameHelper.GetMemberNameForMethod(methodInfo);
var methodNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{methodMemberName}']");
if (methodNode == null)
{
return;
}
var summaryNode = methodNode.SelectSingleNode("summary");
if (summaryNode != null)
{
operation.Summary = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
var remarksNode = methodNode.SelectSingleNode("remarks");
if (remarksNode != null)
{
operation.Description = XmlCommentsTextHelper.Humanize(remarksNode.InnerXml);
}
var responseNodes = methodNode.Select("response");
ApplyResponseTags(operation, responseNodes);
}
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 = ConvertToOpenApiType(parameterInfo.ParameterType, parameter.Schema, example);
}
}
}
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 ApplyParamTags(OpenApiRequestBody requestBody, 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);
}
}
private void ApplyTypeTags(OpenApiSchema schema, Type type)
{
var typeMemberName = XmlCommentsNodeNameHelper.GetMemberNameForType(type);
var typeSummaryNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{typeMemberName}']/summary");
if (typeSummaryNode != null)
{
schema.Description = XmlCommentsTextHelper.Humanize(typeSummaryNode.InnerXml);
}
}
private void ApplyPropertyTags(OpenApiRequestBody requestBody, PropertyInfo propertyInfo)
{
var propertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(propertyInfo);
var propertySummaryNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{propertyMemberName}']/summary");
if (propertySummaryNode != null)
{
requestBody.Description = XmlCommentsTextHelper.Humanize(propertySummaryNode.InnerXml);
}
}
private void TryApplyTypeComments(OpenApiSchema schema, Type type)
{
var typeNodeName = XmlCommentsNodeNameHelper.GetMemberNameForType(type);
var typeNode = _xmlNavigator.SelectSingleNode(string.Format(NodeXPath, typeNodeName));
if (typeNode != null)
{
var summaryNode = typeNode.SelectSingleNode(SummaryTag);
if (summaryNode != null)
{
schema.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
}
}
private void ApplyParamTags(OpenApiSchema schema, ParameterInfo parameterInfo)
{
if (!(parameterInfo.Member is MethodInfo methodInfo))
{
return;
}
var methodMemberName = XmlCommentsNodeNameHelper.GetMemberNameForMethod(methodInfo);
var paramNode = _xmlNavigator.SelectSingleNode(
$"/doc/members/member[@name='{methodMemberName}']/param[@name='{parameterInfo.Name}']");
if (paramNode != null)
{
schema.Description = XmlCommentsTextHelper.Humanize(paramNode.InnerXml);
}
}
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 ApplyPropertiesXmlToPropertyParameters(
IList <OpenApiParameter> parameters,
ApiDescription apiDescription)
{
if (parameters == null)
{
return;
}
foreach (var parameter in parameters)
{
// Check for a corresponding API parameter (from ApiExplorer) that's property-bound?
var propertyParam = apiDescription.ParameterDescriptions
.Where(p => p.ModelMetadata?.ContainerType != null && p.ModelMetadata?.PropertyName != null)
.FirstOrDefault(p => parameter.Name.Equals(p.Name, StringComparison.OrdinalIgnoreCase));
if (propertyParam == null)
{
continue;
}
var metadata = propertyParam.ModelMetadata;
var memberInfo = metadata.ContainerType.GetMember(metadata.PropertyName).FirstOrDefault();
if (memberInfo == null)
{
continue;
}
var memberName = XmlCommentsNodeNameHelper.GetNodeNameForMember(memberInfo);
var memberNode = _xmlNavigator.SelectSingleNode(string.Format(MemberXPath, memberName));
if (memberNode == null)
{
continue;
}
var summaryNode = memberNode.SelectSingleNode(SummaryXPath);
if (summaryNode != null)
{
parameter.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
}
}
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
if (context.MethodInfo == null)
{
return;
}
// If method is from a constructed generic type, look for comments from the generic type method
var targetMethod = context.MethodInfo.DeclaringType.IsConstructedGenericType
? GetGenericTypeMethodOrNullFor(context.MethodInfo)
: context.MethodInfo;
if (targetMethod == null)
{
return;
}
var typeMemberName = XmlCommentsNodeNameHelper.GetMemberNameForType(targetMethod.DeclaringType);
var typeNode = _xmlNavigator.SelectSingleNode(string.Format(MemberXPath, typeMemberName));
// Apply controller-level tags if any
if (typeNode != null)
{
ApplyResponsesXmlToResponses(operation.Responses, typeNode.Select(ResponsesXPath));
}
var methodMemberName = XmlCommentsNodeNameHelper.GetMemberNameForMethod(targetMethod);
var methodNode = _xmlNavigator.SelectSingleNode(string.Format(MemberXPath, methodMemberName));
// Apply method-level tags
if (methodNode != null)
{
ApplyMethodXmlToOperation(operation, methodNode);
ApplyParamsXmlToActionParameters(operation.Parameters, operation.RequestBody, context.ApiDescription, methodNode);
ApplyResponsesXmlToResponses(operation.Responses, methodNode.Select(ResponsesXPath)); // will override controller-level response tags
}
// Special handling for parameters that are bound to model properties
ApplyPropertiesXmlToPropertyParameters(operation.Parameters, context.ApiDescription);
}
private void ApplyParamTags(OpenApiSchema schema, ParameterInfo parameterInfo)
{
if (!(parameterInfo.Member is MethodInfo methodInfo))
{
return;
}
var methodMemberName = XmlCommentsNodeNameHelper.GetMemberNameForMethod(methodInfo);
var paramNode = _xmlNavigator.SelectSingleNode(
$"/doc/members/member[@name='{methodMemberName}']/param[@name='{parameterInfo.Name}']");
if (paramNode != null)
{
schema.Description = XmlCommentsTextHelper.Humanize(paramNode.InnerXml);
var example = paramNode.GetAttribute("example", "");
if (!string.IsNullOrEmpty(example))
{
schema.Example = ConvertToOpenApiType(parameterInfo.ParameterType, schema, example);
}
}
}
private void ApplyFieldOrPropertyTags(OpenApiSchema schema, MemberInfo fieldOrPropertyInfo)
{
var fieldOrPropertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(fieldOrPropertyInfo);
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)
{
schema.Example = OpenApiAnyFactory.CreateFromJson(exampleNode.InnerXml);
}
}
