File: XmlComments\XmlDocumentationIntegrationTests.cs
Web Access
Project: src\src\Grpc\JsonTranscoding\test\Microsoft.AspNetCore.Grpc.Swagger.Tests\Microsoft.AspNetCore.Grpc.Swagger.Tests.csproj (Microsoft.AspNetCore.Grpc.Swagger.Tests)
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
using Greet;
using Microsoft.AspNetCore.Grpc.Swagger.Tests.Infrastructure;
using Microsoft.AspNetCore.Grpc.Swagger.Tests.Services;
using Microsoft.OpenApi.Models;
using Xunit.Abstractions;
 
namespace Microsoft.AspNetCore.Grpc.Swagger.Tests.XmlComments;
 
public class XmlDocumentationIntegrationTests
{
    private readonly ITestOutputHelper _testOutputHelper;
 
    public XmlDocumentationIntegrationTests(ITestOutputHelper testOutputHelper)
    {
        _testOutputHelper = testOutputHelper;
    }
 
    [Fact]
    public void ServiceDescription_ModelHasXmlDocs_UseXmlDocs()
    {
        // Arrange & Act
        var swagger = OpenApiTestHelpers.GetOpenApiDocument<XmlDocServiceWithComments>(_testOutputHelper);
 
        // Assert
        Assert.Equal("XmlDoc", swagger.Tags[0].Name);
        Assert.Equal("XmlDocServiceWithComments XML comment!", swagger.Tags[0].Description);
    }
 
    [Fact]
    public void ServiceDescription_ModelDoesntHaveXmlDocs_UseProtoDocs()
    {
        // Arrange & Act
        var swagger = OpenApiTestHelpers.GetOpenApiDocument<XmlDocService>(_testOutputHelper);
 
        // Assert
        Assert.Equal("XmlDoc", swagger.Tags[0].Name);
        Assert.Equal("XmlDoc!", swagger.Tags[0].Description);
    }
 
    [Fact]
    public void RouteParameter_UseProtoDocs()
    {
        // Arrange & Act
        var swagger = OpenApiTestHelpers.GetOpenApiDocument<XmlDocServiceWithComments>(_testOutputHelper);
 
        // Assert
        var path = swagger.Paths["/v1/greeter/{name}"];
        Assert.Equal("Name field!", path.Operations[OperationType.Get].Parameters[0].Description);
    }
 
    [Fact]
    public void MethodDescription_ModelHasXmlDocs_UseXmlDocs()
    {
        // Arrange & Act
        var swagger = OpenApiTestHelpers.GetOpenApiDocument<XmlDocServiceWithComments>(_testOutputHelper);
 
        // Assert
        var path = swagger.Paths["/v1/greeter/{name}"];
        Assert.Equal("BasicGet XML summary!", path.Operations[OperationType.Get].Summary);
        Assert.Equal("BasicGet XML remarks!", path.Operations[OperationType.Get].Description);
    }
 
    [Fact]
    public void MethodDescription_ModelDoesntHaveXmlDocs_UseProtoDocs()
    {
        // Arrange & Act
        var swagger = OpenApiTestHelpers.GetOpenApiDocument<XmlDocService>(_testOutputHelper);
 
        // Assert
        var path = swagger.Paths["/v1/greeter/{name}"];
        Assert.Equal("BasicGet!", path.Operations[OperationType.Get].Summary);
        Assert.Null(path.Operations[OperationType.Get].Description);
    }
 
    [Fact]
    public void RequestDescription_Root_ModelHasXmlDocs_UseXmlDocs()
    {
        // Arrange & Act
        var swagger = OpenApiTestHelpers.GetOpenApiDocument<XmlDocServiceWithComments>(_testOutputHelper);
 
        // Assert
        var path = swagger.Paths["/v1/greeter"];
        Assert.Equal("Request XML param!", path.Operations[OperationType.Post].RequestBody.Description);
    }
 
    [Fact]
    public void RequestDescription_Root_ModelDoesntHaveXmlDocs_Empty()
    {
        // Arrange & Act
        var swagger = OpenApiTestHelpers.GetOpenApiDocument<XmlDocService>(_testOutputHelper);
 
        // Assert
        var path = swagger.Paths["/v1/greeter"];
        Assert.Null(path.Operations[OperationType.Post].RequestBody.Description);
    }
 
    [Fact]
    public void RequestDescription_Nested_ProtoFieldDocs()
    {
        // Arrange & Act
        var swagger = OpenApiTestHelpers.GetOpenApiDocument<XmlDocService>(_testOutputHelper);
 
        // Assert
        var path = swagger.Paths["/v1/greeter/{name}"];
        Assert.Equal("Detail field!", path.Operations[OperationType.Post].RequestBody.Description);
    }
 
    [Fact]
    public void Parameters_QueryParameters_ProtoFieldDocs()
    {
        // Arrange & Act
        var swagger = OpenApiTestHelpers.GetOpenApiDocument<XmlDocService>(_testOutputHelper);
 
        // Assert
        var path = swagger.Paths["/v1/greeter/query/{name}"];
        Assert.Collection(path.Operations[OperationType.Get].Parameters,
            p =>
            {
                Assert.Equal(ParameterLocation.Path, p.In);
                Assert.Equal("name", p.Name);
                Assert.Equal("Name field!", p.Description);
            },
            p =>
            {
                Assert.Equal(ParameterLocation.Query, p.In);
                Assert.Equal("detail.age", p.Name);
                Assert.Equal("Age field!", p.Description);
            });
    }
 
    [Fact]
    public void Message_UseProtoDocs()
    {
        // Arrange & Act
        var swagger = OpenApiTestHelpers.GetOpenApiDocument<XmlDocServiceWithComments>(_testOutputHelper);
 
        // Assert
        var helloReplyMessage = swagger.Components.Schemas["StringReply"];
        Assert.Equal("StringReply!", helloReplyMessage.Description);
        Assert.Equal("Message field!", helloReplyMessage.Properties["message"].Description);
    }
 
    private class GreeterService : Greeter.GreeterBase
    {
    }
}