public void Humanize_TrimsWhiteSpaceFromStartAndEnd()
{
var input = @"
A line of text
";
var output = XmlCommentsTextHelper.Humanize(input);
Assert.Equal("A line of text", output, false, true);
}
private void ApplyResponseTags(OpenApiOperation operation, XPathNodeIterator responseNodes)
{
while (responseNodes.MoveNext())
{
var code = responseNodes.Current !.GetAttribute("code", "");
var response = operation.Responses.ContainsKey(code)
? operation.Responses[code]
: operation.Responses[code] = new OpenApiResponse();
response.Description = XmlCommentsTextHelper.Humanize(responseNodes.Current.InnerXml);
}
}
private void ApplyResponsesXmlToResponses(IDictionary <string, OpenApiResponse> responses, XPathNodeIterator responseNodes)
{
while (responseNodes.MoveNext())
{
var code = responseNodes.Current.GetAttribute("code", "");
var response = responses.ContainsKey(code)
? responses[code]
: responses[code] = new OpenApiResponse();
response.Description = XmlCommentsTextHelper.Humanize(responseNodes.Current.InnerXml);
}
}
public string GetTypeSummary(string typeFullName)
{
foreach (var xmlDoc in _xmlDocs)
{
var xnMember = xmlDoc.SelectSingleNode($"/doc/members/member[@name='T:{typeFullName}']");
if (xnMember != null)
{
var xnSummary = xnMember.SelectSingleNode("summary");
return(XmlCommentsTextHelper.Humanize(xnSummary.InnerXml));
}
}
return(null);
}
public string GetPropertyExample(PropertyInfo propertyInfo)
{
var propertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(propertyInfo);
var propertyExampleNode = this.xpathNavigator.SelectSingleNode($"/doc/members/member[@name='{propertyMemberName}']/example");
if (propertyExampleNode == null)
{
return(string.Empty);
}
var example = XmlCommentsTextHelper.Humanize(propertyExampleNode.InnerXml);
return(example);
}
public string GetSummaryForType(Type type)
{
var memberName = XmlCommentsNodeNameHelper.GetMemberNameForType(type);
var typeNode = this.xpathNavigator.SelectSingleNode(string.Format(XmlDocumentationService.MemberXPath, memberName));
if (typeNode == null)
{
return(string.Empty);
}
var summaryNode = typeNode.SelectSingleNode(XmlDocumentationService.SummaryTag);
return(XmlCommentsTextHelper.Humanize(summaryNode.InnerXml));
}
private void ApplyResponsesXmlToResponses(ArrayElement responses, XPathNodeIterator responseNodes)
{
while (responseNodes.MoveNext())
{
var code = responseNodes.Current.GetAttribute("code", "");
var response = responses.TryGetElement <Response>(code);
if (response == null)
{
continue;
}
response.Description.Value = XmlCommentsTextHelper.Humanize(responseNodes.Current.InnerXml);
}
}
private void TryApplyTypeComments(OpenApiSchema schema, Type type)
{
var typeNode = xmlDocProvider.GetNodeForType(type);
if (typeNode == null)
{
return;
}
var summaryNode = typeNode.SelectSingleNode(SummaryTag);
if (summaryNode != null)
{
schema.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
}
public void SetCommentToProperty(PropertyType propertyType, PropertyInfo property)
{
if (!Cannavigator())
{
return;
}
var id = GetCommentIdForProperty(property);
var typeNode = navigator.SelectSingleNode(string.Format(MemberXPath, id));
var summaryNode = typeNode?.SelectSingleNode(SummaryXPath);
if (summaryNode != null)
{
propertyType.Description.Value = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
}
public void SetCommentToClass(ObjectType ot, Type type)
{
if (!Cannavigator())
{
return;
}
var id = GetCommentIdForType(type);
var typeNode = navigator.SelectSingleNode(string.Format(MemberXPath, id));
var summaryNode = typeNode?.SelectSingleNode(SummaryXPath);
if (summaryNode != null)
{
ot.Description.Value = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
}
private void ApplyParamsXmlToActionParameters(ArrayElement queryParameters, XPathNavigator methodNode)
{
if (!queryParameters.HasElements)
{
return;
}
foreach (var item in queryParameters.Elements)
{
var paramNode = methodNode.SelectSingleNode(string.Format(ParamXPath, item.Key));
if (paramNode != null && item is Parameter p)
{
p.Description.Value = XmlCommentsTextHelper.Humanize(paramNode.InnerXml);
}
}
}
private void ApplyPropertyComments(OpenApiSchema propertySchema, MemberInfo memberInfo)
{
var memberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(memberInfo);
if (!_inheritedDocs.ContainsKey(memberName))
{
return;
}
if (_excludedTypes.Any() && _excludedTypes.ToList()
.Contains(((PropertyInfo)memberInfo).PropertyType))
{
return;
}
var cref = _inheritedDocs[memberName];
var target = GetTargetRecursive(memberInfo, cref);
var targetXmlNode = GetMemberXmlNode(XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(target));
if (targetXmlNode == null)
{
return;
}
var summaryNode = targetXmlNode.SelectSingleNode(SummaryTag);
if (summaryNode != null)
{
propertySchema.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
if (_includeRemarks)
{
var remarksNode = targetXmlNode.SelectSingleNode(RemarksTag);
if (remarksNode != null && !string.IsNullOrWhiteSpace(remarksNode.InnerXml))
{
propertySchema.Description += $" ({XmlCommentsTextHelper.Humanize(remarksNode.InnerXml)})";
}
}
}
var exampleNode = targetXmlNode.SelectSingleNode(ExampleTag);
if (exampleNode != null)
{
propertySchema.Example = new OpenApiString(XmlCommentsTextHelper.Humanize(exampleNode.InnerXml));
}
}
/// <summary>
/// Apply filter.
/// </summary>
/// <param name="schema"><see cref="OpenApiSchema"/>.</param>
/// <param name="context"><see cref="SchemaFilterContext"/>.</param>
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
if (_excludedTypes.Any() && _excludedTypes.ToList().Contains(context.Type))
{
return;
}
// Try to apply a description for inherited types.
var memberName = XmlCommentsNodeNameHelper.GetMemberNameForType(context.Type);
if (string.IsNullOrEmpty(schema.Description) && _inheritedDocs.ContainsKey(memberName))
{
var cref = _inheritedDocs[memberName];
var target = GetTargetRecursive(context.Type, cref);
var targetXmlNode = GetMemberXmlNode(XmlCommentsNodeNameHelper.GetMemberNameForType(target));
var summaryNode = targetXmlNode?.SelectSingleNode(SummaryTag);
if (summaryNode != null)
{
schema.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
if (_includeRemarks)
{
var remarksNode = targetXmlNode.SelectSingleNode(RemarksTag);
if (remarksNode != null && !string.IsNullOrWhiteSpace(remarksNode.InnerXml))
{
schema.Description += $" ({XmlCommentsTextHelper.Humanize(remarksNode.InnerXml)})";
}
}
}
}
if (schema.Properties == null)
{
return;
}
// Add the summary and examples for the properties.
foreach (var entry in schema.Properties)
{
var memberInfo = ((TypeInfo)context.Type).DeclaredMembers?.FirstOrDefault(p => p.Name.Equals(entry.Key, StringComparison.OrdinalIgnoreCase));
if (memberInfo != null)
{
ApplyPropertyComments(entry.Value, memberInfo);
}
}
}
private void ApplyMethodXmlToOperation(OpenApiOperation operation, XPathNavigator methodNode)
{
var summaryNode = methodNode.SelectSingleNode(SummaryXPath);
if (summaryNode != null)
{
operation.Summary = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
var remarksNode = methodNode.SelectSingleNode(RemarksXPath);
if (remarksNode != null)
{
operation.Description = XmlCommentsTextHelper.Humanize(remarksNode.InnerXml);
}
}
private void ApplyMethodXmlToOperation(Operation operation, XPathNavigator methodNode, ApiDescription apiDescription)
{
XPathNavigator xpathNavigator1 = methodNode.SelectSingleNode("summary");
operation.Summary = GetMemberPermission(apiDescription);
if (xpathNavigator1 != null)
{
operation.Summary += XmlCommentsTextHelper.Humanize(xpathNavigator1.InnerXml);
}
XPathNavigator xpathNavigator2 = methodNode.SelectSingleNode("remarks");
if (xpathNavigator2 == null)
{
return;
}
operation.Description = XmlCommentsTextHelper.Humanize(xpathNavigator2.InnerXml);
}
public void Humanize_TrimsCommonSpaceTabIndentations()
{
// Common indentation seen in visual studio: {space}{tab}
var input = @"
## Heading 1
A line of text
" ;
var output = XmlCommentsTextHelper.Humanize(input);
Assert.Equal(
@"## Heading 1
A line of text",
output
);
}
public void Humanize_DoesNotTrimInconsistentIndentations()
{
var input = @"
Space Indentation Line 1
Space Indentation Line 2
Misplaced Tab Indentation
Space Indentation Line 4
";
var output = XmlCommentsTextHelper.Humanize(input);
Assert.Equal(
@" Space Indentation Line 1
Space Indentation Line 2
Misplaced Tab Indentation
Space Indentation Line 4",
output, false, true);
}
private static string TryGetMemberComments(MemberInfo memberInfo, IEnumerable <XPathNavigator> xmlNavigators)
{
if (xmlNavigators == null)
{
return(string.Empty);
}
foreach (var xmlNavigator in xmlNavigators)
{
var nodeNameForMember = GetNodeNameForMember(memberInfo);
var xpathNavigator1 = xmlNavigator.SelectSingleNode(
$"/doc/members/member[@name='{nodeNameForMember}']");
var xpathNavigator2 = xpathNavigator1?.SelectSingleNode("summary");
return(xpathNavigator2 != null?XmlCommentsTextHelper.Humanize(xpathNavigator2.InnerXml) : string.Empty);
}
return(string.Empty);
}
public void SetCommentToMethod(ApiDescription api, Method method)
{
if (Cannavigator() && api.ActionDescriptor is ControllerActionDescriptor controller)
{
var id = GetCommentIdForMethod(controller.MethodInfo);
var methodNode = navigator.SelectSingleNode(string.Format(MemberXPath, id));
if (methodNode == null)
{
return;
}
var summaryNode = methodNode.SelectSingleNode(SummaryXPath);
if (summaryNode != null)
{
method.Description.Value = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
}
ApplyResponsesXmlToResponses(method.Responses, methodNode.Select(ResponsesXPath));
ApplyParamsXmlToActionParameters(method.QueryParameters, methodNode);
}
}
private void ApplyTypeTags(OpenApiSchema schema, Type type)
{
if (_excludedTypes.Any() && _excludedTypes.ToList().Contains(type))
{
return;
}
var typeMemberName = XmlCommentsNodeNameHelper.GetMemberNameForType(type);
var typeSummaryNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{typeMemberName}']/{SummaryTag}");
if (typeSummaryNode != null)
{
var typeRemarksNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{typeMemberName}']/{RemarksTag}");
if (typeRemarksNode != null && !string.IsNullOrWhiteSpace(typeRemarksNode.InnerXml))
{
schema.Description +=
$" ({XmlCommentsTextHelper.Humanize(typeRemarksNode.InnerXml)})";
}
}
}
private void ApplyParamsXmlToActionParameters(IList <IParameter> parameters, XPathNavigator methodNode, ApiDescription apiDescription)
{
if (parameters == null)
{
return;
}
foreach (IParameter parameter1 in (IEnumerable <IParameter>)parameters)
{
IParameter parameter = parameter1;
ParameterDescriptor parameterDescriptor = apiDescription.ActionDescriptor.Parameters.FirstOrDefault <ParameterDescriptor>((Func <ParameterDescriptor, bool>)(p => parameter.Name.Equals(p.BindingInfo?.BinderModelName ?? p.Name, StringComparison.OrdinalIgnoreCase)));
if (parameterDescriptor != null)
{
XPathNavigator xpathNavigator = methodNode.SelectSingleNode(string.Format("param[@name='{0}']", (object)parameterDescriptor.Name));
if (xpathNavigator != null)
{
parameter.Description = XmlCommentsTextHelper.Humanize(xpathNavigator.InnerXml);
}
}
}
}
private void ApplyPropertyTags(OpenApiRequestBody requestBody, PropertyInfo propertyInfo)
{
if (propertyInfo.DeclaringType != null && _excludedTypes.Any() && _excludedTypes.ToList().Contains(propertyInfo.DeclaringType))
{
return;
}
var propertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(propertyInfo);
var propertySummaryNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{propertyMemberName}']/{SummaryTag}");
if (propertySummaryNode != null)
{
var propertyRemarksNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{propertyMemberName}']/{RemarksTag}");
if (propertyRemarksNode != null &&
!string.IsNullOrWhiteSpace(propertyRemarksNode.InnerXml) &&
!requestBody.Description.Contains(XmlCommentsTextHelper.Humanize(propertyRemarksNode.InnerXml)))
{
requestBody.Description +=
$" ({XmlCommentsTextHelper.Humanize(propertyRemarksNode.InnerXml)})";
}
}
}
public IEnumerable <KeyValuePair <string, int> > GetEnumValuesSummary(Type type)
{
var lstRetn = new List <KeyValuePair <string, int> >();
var enumTypeName = type.FullName;
var xmlDoc = _xmlDocs.FirstOrDefault(p =>
{
var xnMember = p.SelectSingleNode($"/doc/members/member[@name='T:{enumTypeName}']");
return(xnMember != null);
});
var eVals = Enum.GetValues(type);
foreach (var eVal in eVals)
{
var xnField = xmlDoc?.SelectSingleNode($"/doc/members/member[@name=\'F:{enumTypeName}.{eVal}\']");
var sStr = xnField != null?XmlCommentsTextHelper.Humanize(xnField.SelectSingleNode("summary").InnerXml) : eVal.ToString();
lstRetn.Add(new KeyValuePair <string, int>(sStr, (int)eVal));
}
return(lstRetn);
}
public void Humanize_TrimsCommonSpaceIndentations()
{
var input = @"
## Heading 1
* list item 1
## Heading 2
POST /api/test
{
""prop1"": {
""name"": ""value""
}
}
";
var output = XmlCommentsTextHelper.Humanize(input);
Assert.Equal(
@"## Heading 1
* list item 1
## Heading 2
POST /api/test
{
""prop1"": {
""name"": ""value""
}
}" ,
output,
false,
true
);
}
private void ApplyFieldOrPropertyTags(OpenApiSchema schema, MemberInfo fieldOrPropertyInfo)
{
if (fieldOrPropertyInfo.DeclaringType != null && _excludedTypes.Any() && _excludedTypes.ToList().Contains(fieldOrPropertyInfo.DeclaringType))
{
return;
}
var fieldOrPropertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(fieldOrPropertyInfo);
var fieldOrPropertyNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{fieldOrPropertyMemberName}']");
var summaryNode = fieldOrPropertyNode?.SelectSingleNode(SummaryTag);
if (summaryNode != null)
{
var remarksNode = fieldOrPropertyNode.SelectSingleNode(RemarksTag);
if (remarksNode != null &&
!string.IsNullOrWhiteSpace(remarksNode.InnerXml) &&
!schema.Description.Contains(XmlCommentsTextHelper.Humanize(remarksNode.InnerXml)))
{
schema.Description +=
$" ({XmlCommentsTextHelper.Humanize(remarksNode.InnerXml)})";
}
}
}
/// <summary>
/// Apply filter.
/// </summary>
/// <param name="swaggerDoc"><see cref="OpenApiDocument"/>.</param>
/// <param name="context"><see cref="DocumentFilterContext"/>.</param>
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)
{
if (_excludedTypes.Any() && _excludedTypes.ToList().Contains(nameAndType.Value))
{
continue;
}
var memberName = XmlCommentsNodeNameHelper.GetMemberNameForType(nameAndType.Value);
var typeNode = _xmlNavigator.SelectSingleNode(string.Format(MemberXPath, memberName));
var summaryNode = typeNode?.SelectSingleNode(SummaryTag);
if (summaryNode != null)
{
var remarksNode = typeNode.SelectSingleNode(RemarksTag);
if (remarksNode != null && !string.IsNullOrWhiteSpace(remarksNode.InnerXml))
{
var tag = swaggerDoc.Tags.FirstOrDefault(t => t.Name.Equals(nameAndType.Key));
if (tag != null &&
!tag.Description.Contains(XmlCommentsTextHelper.Humanize(remarksNode.InnerXml)))
{
swaggerDoc.Tags.First(t => t.Name.Equals(nameAndType.Key)).Description +=
$" ({XmlCommentsTextHelper.Humanize(remarksNode.InnerXml)})";
}
}
}
}
}
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 = JsonMapper.CreateFromJson(exampleNode.InnerXml);
}
}
private void ApplyPropertiesXmlToPropertyParameters(IList <IParameter> parameters, ApiDescription apiDescription)
{
if (parameters == null)
{
return;
}
foreach (IParameter parameter1 in (IEnumerable <IParameter>)parameters)
{
IParameter parameter = parameter1;
ApiParameterDescription parameterDescription = apiDescription.ParameterDescriptions.Where <ApiParameterDescription>((Func <ApiParameterDescription, bool>)(p =>
{
if (p.ModelMetadata?.ContainerType != (Type)null)
{
return(p.ModelMetadata?.PropertyName != null);
}
return(false);
})).FirstOrDefault <ApiParameterDescription>((Func <ApiParameterDescription, bool>)(p => parameter.Name.Equals(p.Name, StringComparison.OrdinalIgnoreCase)));
if (parameterDescription != null)
{
ModelMetadata modelMetadata = parameterDescription.ModelMetadata;
MemberInfo memberInfo = ((IEnumerable <MemberInfo>)modelMetadata.ContainerType.GetMember(modelMetadata.PropertyName)).FirstOrDefault <MemberInfo>();
if (!(memberInfo == (MemberInfo)null))
{
XPathNavigator xpathNavigator1 = this._xmlNavigator.SelectSingleNode(string.Format("/doc/members/member[@name='{0}']", (object)XmlCommentsMemberNameHelper.GetMemberNameForMember(memberInfo)));
if (xpathNavigator1 != null)
{
XPathNavigator xpathNavigator2 = xpathNavigator1.SelectSingleNode("summary");
if (xpathNavigator2 != null)
{
parameter.Description = XmlCommentsTextHelper.Humanize(xpathNavigator2.InnerXml);
}
}
}
}
}
}
private void ApplyResponsesXmlToResponses(IDictionary <string, Response> responses, XPathNodeIterator responseNodes)
{
while (responseNodes.MoveNext())
{
string attribute = responseNodes.Current.GetAttribute("code", "");
(responses.ContainsKey(attribute) ? responses[attribute] : (responses[attribute] = new Response())).Description = XmlCommentsTextHelper.Humanize(responseNodes.Current.InnerXml);
}
}
