在描述中添加指向 Swagger 中其他操作的链接（通过 Swashbuckle）

Question

根据Swashbuckle的文档，最新版本仅支持少量 XML 注释。目前似乎不支持诸如<example>或之类的 XML 注释，但将在 Swashbuckle v6 中实现。<see>

在此之前，有一种解决方法我可以做模拟天生的行为<example>或<see>？

我想以某种方式<see>在<summary>枚举中添加一个链接（与 cref 一起使用），该链接在端点模型下列出，以指向枚举的相应端点（Swagger 中的另一个端点，它获取类型列表）那个枚举）。

编辑（不知道如何在评论中格式化）：

我希望 Swagger 检测<see>并显示枚举描述中指向不同端点的链接

/// <summary>
/// Generic description. 
/// Find enum types <see cref="ContactEntityType">here</see>
/// </summary>
[PropertyRequired, PropertyStringAsEnum(typeof(ContactEntityType))]
[DataMember(Name = "entityType")]
public NamedReference EntityType { get; set; }

Answer 1

2022年最新版本的swagger支持参数注释。

/// <param name="MyParamaterName" example="123"> Should be defined as model MyModelName</param>
[HttpPost]
[Route("SomeWebApiFunction")]
public async Task<bool> SomeWebApiFunction(MyModelName MyParamaterName)
{
    return true;
}

public class MyModelName
{
    public string PropName { get; set; }
}

Swaggers 非常擅长为每个部分提供唯一的 id，您可以使用检查元素检查每个部分的 id 属性。这使得在文档中链接变得非常容易。例如，我们可以添加一个链接来滚动到MyModelName描述；

/// <param name="MyParamaterName" example="123"> Should be defined as model <a href='#model-MyModelName'>MyModelName</a></param>

别忘了IncludeXmlComments

builder.Services.AddSwaggerGen(c => {
    string fileName = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var filePath = Path.Combine(AppContext.BaseDirectory, fileName);
    c.IncludeXmlComments(filePath);
});

如果您使用 Visual Studio，请确保打开“生成 XML 注释”。

如果您使用 Asp.net Core 并且未生成 xml，则必须在文件中添加以下PropertyGroup行.csproj。

<PropertyGroup>  
<DocumentationFile>bin\$(Configuration)\$(TargetFramework)\YourApplicationNameGoesHere.xml</DocumentationFile>
</PropertyGroup>

将YourApplicationNameGoesHere替换为您的应用程序的名称。如果由于某种原因您不知道 xml 文件名，您可以在项目构建的输出文件夹中找到它。

Answer 2

您可以使用ISchemaFilter或IDocumentFilter来修改生成的 SwaggerDoc。

以下是一些示例：

    private class ApplySchemaVendorExtensions : ISchemaFilter
    {
        public void Apply(Schema schema, SchemaRegistry schemaRegistry, Type type)
        {
            // Modify the example values in the final SwaggerDocument
            //
            if (schema.properties != null)
            {
                foreach (var p in schema.properties)
                {
                    switch (p.Value.format)
                    {
                        case "int32":
                            p.Value.example = 123;
                            break;
                        case "double":
                            p.Value.example = 9858.216;
                            break;
                    }
                }
            }
        }
    }

_

    private class ApplyDocumentVendorExtensions : IDocumentFilter
    {
        public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
        {
            schemaRegistry.GetOrRegister(typeof(ExtraType));
            //schemaRegistry.GetOrRegister(typeof(BigClass));

            var paths = new Dictionary<string, PathItem>(swaggerDoc.paths);
            swaggerDoc.paths.Clear();
            foreach (var path in paths)
            {
                if (path.Key.Contains("foo"))
                    swaggerDoc.paths.Add(path);
            }
        }
    }

要添加链接，只需使用锚标记：

/// <summary>Details - testing anchor: <a href="?filter=TestPost">TestPost</a></summary>