public void When_method_is_inherited_from_generic_class_then_xml_docs_are_correct()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var singleSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.Single)).GetXmlDocsSummary();
var multiSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.Multi)).GetXmlDocsSummary();
var multiGenericParameterSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.MultiGenericParameter)).GetXmlDocsSummary();
var nestedGenericParameterSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.NestedGenericParameter)).GetXmlDocsSummary();
var singleAsyncSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.SingleAsync)).GetXmlDocsSummary();
var multiAsyncSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.MultiAsync)).GetXmlDocsSummary();
var multiGenericParameterAsyncSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.MultiGenericParameterAsync)).GetXmlDocsSummary();
var nestedGenericParameterAsyncSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.NestedGenericParameterAsync)).GetXmlDocsSummary();
//// Assert
Assert.Equal("Single", singleSummary);
Assert.Equal("Multi", multiSummary);
Assert.Equal("MultiGenericParameter", multiGenericParameterSummary);
Assert.Equal("NestedGenericParameter", nestedGenericParameterSummary);
Assert.Equal("SingleAsync", singleAsyncSummary);
Assert.Equal("MultiAsync", multiAsyncSummary);
Assert.Equal("MultiGenericParameterAsync", multiGenericParameterAsyncSummary);
Assert.Equal("NestedGenericParameterAsync", nestedGenericParameterAsyncSummary);
}
public void Process(DocumentProcessorContext context)
{
try
{
foreach (var controllerType in context.ControllerTypes)
{
var attribute = controllerType.GetCustomAttribute <ApiExplorerSettingsAttribute>();
if (attribute != null)
{
var tag = context.Document.Tags.FirstOrDefault(x => x.Name == attribute.GroupName);
if (tag != null)
{
var description = controllerType.GetXmlDocsSummary();
if (description != null)
{
tag.Description ??= string.Empty;
if (!tag.Description.Contains(description))
{
tag.Description += "\n\n" + description;
}
}
}
}
}
}
finally
{
XmlDocs.ClearCache();
}
}
public void When_xml_doc_is_in_working_dir_then_it_is_found()
{
//// Arrange
XmlDocs.ClearCache();
_ = Directory.CreateDirectory("./wd");
File.WriteAllText("./wd/System.Drawing.Primitives.xml", @"<?xml version=""1.0""?>
<doc>
<assembly><name>System.Drawing.Primitives</name></assembly>
<members>
<member name=""T:System.Drawing.Point"">
<summary>A point.</summary>
</member>
</members>
</doc>");
Directory.SetCurrentDirectory("./wd");
//// Act
var summary = typeof(Point).GetXmlDocsSummary();
//// Clean up
Directory.SetCurrentDirectory("..");
Directory.Delete("./wd", recursive: true);
//// Assert
Assert.Equal("A point.", summary);
}
internal static XmlDocs GetXmlDocs(string xmlDocPath)
{
var collect = new XmlDocs();
if (string.IsNullOrEmpty(xmlDocPath) || !File.Exists(xmlDocPath))
{
return(collect);
}
using (var fileStream = File.Open(xmlDocPath, FileMode.Open, FileAccess.Read))
{
using (var reader = XmlReader.Create(fileStream))
{
while (!reader.EOF)
{
reader.Read();
if (reader.Name != "member" || !reader.IsStartElement())
{
continue;
}
var doc = GetDoc(reader);
collect.Add(doc.Name, doc);
}
}
}
return(collect);
}
public void When_xml_docs_is_read_for_cecil_type_then_it_works()
{
// Arranage
var assemblyPath = typeof(XmlDocsExtensionsTests).Assembly.CodeBase.Replace("file:///", string.Empty);
var xmlPath = assemblyPath.Replace(".dll", ".xml");
var assembly = AssemblyDefinition.ReadAssembly(assemblyPath);
var module = assembly.Modules.Last();
var type = module.GetTypes().Single(t => t.Name.Contains(nameof(MyTest)));
var method = type.Methods.First(m => m.Name == nameof(MyTest.MyMethod));
var document = XmlDocs.LoadDocument(xmlPath);
// Act
var typeSummary = type.GetXmlDocsTag("summary", document);
var constructorSummary = type.Methods.First(m => m.IsConstructor).GetXmlDocsTag("summary", document);
var property = type.Properties.First().GetXmlDocsSummary(document);
var methodSummary = method.GetXmlDocsTag("summary", document);
var parameter = method.Parameters.Last().GetXmlDocs(document);
var returnParameter = method.MethodReturnType.GetXmlDocs(document);
// Assert
Assert.Equal("My class.", typeSummary);
Assert.Equal("My constructor.", constructorSummary);
Assert.Equal("My property.", property);
Assert.Equal("My method.", methodSummary);
Assert.Equal("My param.", parameter);
Assert.Equal("My return.", returnParameter);
}
/// <summary>Generates or gets the cached Swagger specification.</summary>
/// <param name="context">The context.</param>
/// <returns>The Swagger specification.</returns>
protected virtual async Task <string> GetDocumentAsync(HttpContext context)
{
var documentKey = _settings.CreateDocumentCacheKey?.Invoke(context.Request) ?? string.Empty;
Tuple <string, ExceptionDispatchInfo, DateTimeOffset> document;
lock (_documentsCacheLock)
{
_documentsCache.TryGetValue(documentKey, out document);
}
if (document?.Item2 != null &&
document.Item3 + _settings.ExceptionCacheTime > DateTimeOffset.UtcNow)
{
document.Item2.Throw();
}
var apiDescriptionGroups = _apiDescriptionGroupCollectionProvider.ApiDescriptionGroups;
if (apiDescriptionGroups.Version == Volatile.Read(ref _version) &&
document?.Item1 != null)
{
return(document.Item1);
}
try
{
var openApiDocument = await GenerateDocumentAsync(context);
var data = _path.ToLowerInvariant().Contains(".yaml") ?
OpenApiYamlDocument.ToYaml(openApiDocument) :
openApiDocument.ToJson();
XmlDocs.ClearCache();
CachedType.ClearCache();
_version = apiDescriptionGroups.Version;
lock (_documentsCacheLock)
{
_documentsCache[documentKey] = new Tuple <string, ExceptionDispatchInfo, DateTimeOffset>(
data, null, DateTimeOffset.UtcNow);
}
return(data);
}
catch (Exception exception)
{
lock (_documentsCacheLock)
{
_documentsCache[documentKey] = new Tuple <string, ExceptionDispatchInfo, DateTimeOffset>(
null, ExceptionDispatchInfo.Capture(exception), DateTimeOffset.UtcNow);
}
throw;
}
}
public void When_summary_has_generic_tags_then_it_is_converted()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var summary = typeof(WithGenericTagsInXmlDoc).GetProperty("Foo").GetXmlDocsSummary();
//// Assert
Assert.Equal("This are some tags.", summary);
}
public void When_type_has_summary_then_it_is_read()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var summary = typeof(Publisher).GetXmlDocsSummary();
//// Assert
Assert.False(string.IsNullOrWhiteSpace(summary));
}
public void When_type_is_in_NuGet_then_xml_docs_should_be_found()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var summary = typeof(JsonSchema).GetXmlDocsSummary();
//// Assert
Assert.False(string.IsNullOrWhiteSpace(summary));
}
public void WhenTypeInheritsFromGenericType_ThenXmlDocsIsFound()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var fooSummary = typeof(MyController).GetMethod(nameof(BaseController <string> .Test)).GetXmlDocsSummary();
//// Assert
Assert.Equal("Base method.", fooSummary);
}
public void When_summary_has_paramref_tag_then_it_is_converted()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var summary = typeof(WithParamrefTagInXmlDoc).GetMethod("Foo").GetXmlDocsSummary();
//// Assert
Assert.Equal("Returns name.", summary);
}
public void When_property_has_inheritdoc_on_interface_then_it_is_resolved()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var propertySummary = typeof(ClassWithInheritdocOnInterface).GetProperty("Foo").GetXmlDocsSummary();
//// Assert
Assert.Equal("Foo.", propertySummary);
}
public void When_method_has_inheritdoc_then_on_interface_it_is_resolved()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var methodSummary = typeof(ClassWithInheritdocOnInterface).GetMethod("Bar").GetXmlDocsSummary();
//// Assert
Assert.Equal("Bar.", methodSummary);
}
public void When_summary_has_see_tag_then_it_is_converted()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var summary = typeof(WithSeeTagInXmlDoc).GetProperty("Foo").GetXmlDocsSummary();
//// Assert
Assert.Equal("null for the default Record. See this and this at https://github.com/rsuter/njsonschema.", summary);
}
public void When_type_is_in_AspNetCore_then_docs_should_be_found()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var summary = typeof(ProblemDetails).GetXmlDocsSummary();
//// Assert
Assert.False(string.IsNullOrWhiteSpace(summary));
}
public void When_xml_doc_is_missing_then_summary_is_missing()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var summary = typeof(Point).GetXmlDocsSummary();
var summary2 = typeof(Point).GetXmlDocsSummary();
//// Assert
Assert.Empty(summary);
}
public void When_parameter_has_inheritdoc_on_interface_then_it_is_resolved()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var parameterXml = typeof(ClassWithInheritdocOnInterface).GetMethod("Bar").GetParameters()
.Single(p => p.Name == "baz").GetXmlDocs();
//// Assert
Assert.Equal("Baz.", parameterXml);
}
public void WhenTypeInheritsFromGenericType_ThenMethodAndPropertyWithGenericParametersResolvesCorrectXml()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var summaryMethod = typeof(InheritedGenericClass).GetMethod("SingleAsync").GetXmlDocsSummary();
var summaryProperty = typeof(InheritedGenericClass).GetProperty("Baz").GetXmlDocsSummary();
//// Assert
Assert.Equal("SingleAsync", summaryMethod);
Assert.Equal("Baz", summaryProperty);
}
public void When_record_has_param_properties_then_xml_docs_is_read()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var listItemsSummary = typeof(ListItems).GetXmlDocsSummary();
var pageNumberSummary = typeof(ListItems).GetRuntimeProperty("PageNumber").GetXmlDocsSummary();
//// Assert
Assert.Equal("Returns a list of items.", listItemsSummary);
Assert.Equal("The page number.", pageNumberSummary);
}
public void When_method_is_inherited_then_xml_docs_are_correct()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var fooSummary = typeof(MyClass).GetMethod(nameof(MyClass.Foo)).GetXmlDocsSummary();
var barSummary = typeof(MyClass).GetMethod(nameof(MyClass.Bar)).GetXmlDocsSummary();
//// Assert
Assert.Equal("Foo", fooSummary);
Assert.Equal("Bar", barSummary);
}
public void When_xml_doc_with_multiple_breaks_is_read_then_they_are_not_stripped_away()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var summary = typeof(WithComplexXmlDoc).GetProperty("Foo").GetXmlDocsSummary();
//// Assert
Assert.Contains("\n\n", summary);
Assert.Contains(" * Users", summary);
Assert.Equal(summary.Trim(), summary);
}
public void When_inheritdocs_is_availble_in_inheritance_chain_then_it_is_resolved()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var searchStringProperty = typeof(BusinessProcessSearchResult).GetRuntimeProperty("SearchString").GetXmlDocsSummary();
var isSearchStringRewrittenProperty = typeof(BusinessProcessSearchResult).GetRuntimeProperty("IsSearchStringRewritten").GetXmlDocsSummary();
var pageTokenProperty = typeof(BusinessProcessSearchResult).GetRuntimeProperty("PageToken").GetXmlDocsSummary();
//// Assert
Assert.True(!string.IsNullOrWhiteSpace(searchStringProperty));
Assert.True(!string.IsNullOrWhiteSpace(isSearchStringRewrittenProperty));
Assert.True(!string.IsNullOrWhiteSpace(pageTokenProperty));
}
/// <summary>
/// Load an XML document.
/// </summary>
/// <param name="filename">The filename of the document to load.</param>
/// <returns>The loaded document.</returns>
public static XmlDocument GetXml(string filename)
{
ValidateFilename(filename);
if (XmlDocs.ContainsKey(filename))
{
return(XmlDocs[filename]);
}
var xml = new XmlDocument();
xml.Load(filename);
XmlDocs.Add(filename, xml);
return(xml);
}
public void ReadXmlDocs()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var singleSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.Single)).GetXmlDocsSummary();
var multiSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.Multi)).GetXmlDocsSummary();
var multiGenericParameterSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.MultiGenericParameter)).GetXmlDocsSummary();
var nestedGenericParameterSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.NestedGenericParameter)).GetXmlDocsSummary();
var singleAsyncSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.SingleAsync)).GetXmlDocsSummary();
var multiAsyncSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.MultiAsync)).GetXmlDocsSummary();
var multiGenericParameterAsyncSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.MultiGenericParameterAsync)).GetXmlDocsSummary();
var nestedGenericParameterAsyncSummary = typeof(InheritedGenericClass2).GetMethod(nameof(InheritedGenericClass2.NestedGenericParameterAsync)).GetXmlDocsSummary();
//// Complete
_counter.Increment();
}
public void When_xml_doc_contains_xml_then_it_is_fully_read()
{
//// Arrange
XmlDocs.ClearCache();
//// Act
var element = typeof(WithTagsInXmlDoc).GetProperty("Foo").GetXmlDocsElement();
var responses = element.Elements("response");
//// Assert
Assert.Equal(2, responses.Count());
Assert.Equal("Account created", responses.First().Value);
Assert.Equal("201", responses.First().Attribute("code").Value);
Assert.Equal("Username already in use", responses.Last().Value);
Assert.Equal("400", responses.Last().Attribute("code").Value);
}
public void WhenTypeInheritsFromGenericType_ThenMethodAndPropertyWithGenericParametersResolvesCorrectXml()
{
// Arranage
var assemblyPath = typeof(XmlDocsExtensionsTests).Assembly.CodeBase.Replace("file:///", string.Empty);
var xmlPath = assemblyPath.Replace(".dll", ".xml");
var assembly = AssemblyDefinition.ReadAssembly(assemblyPath);
var module = assembly.Modules.Last();
var type = module.GetTypes().Single(t => t.Name.Contains("BaseGenericClass"));
var method = type.Methods.First(m => m.Name == nameof(InheritedGenericClass.SingleAsync));
var method2 = type.Methods.First(m => m.Name == nameof(InheritedGenericClass.MultiAsync));
var document = XmlDocs.LoadDocument(xmlPath);
//// Act
var summaryMethod = method.GetXmlDocsTag("summary", document);
var summaryMethod2 = method2.GetXmlDocsTag("summary", document);
var summaryProperty = type.Properties.First().GetXmlDocsSummary(document);
//// Assert
Assert.Equal("SingleAsync", summaryMethod);
Assert.Equal("MultiAsync", summaryMethod2);
Assert.Equal("Baz", summaryProperty);
}
