将描述中的链接添加到 Swagger 中的其他操作（通过 Swashbuckle）

Question

根据 documentation for Swashbuckle, only a few XML comments are supported in the latest version. It seems like XML comments such as <example> or <see> are not currently supported but will be implemented in Swashbuckle v6.

在那之前，是否有我可以模仿 <example> 或 <see> 行为的解决方法？

我想以某种方式在端点模型下列出的枚举的 <summary> 中添加一个 link（使用 <see> 和 cref）到指向枚举的相应端点（Swagger 中获取该枚举类型列表的不同端点）。

编辑（不确定如何在评论中格式化）：

我希望 Swagger 检测 <see> 并在枚举的描述中显示 link 到不同的端点

/// <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

您可以使用 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);
            }
        }
    }

要添加 link 只需使用锚标记 :

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

Answer 2

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，您可以使用 inspect 元素检查每个部分的 id 属性。这使得在文档周围 link 变得非常容易。例如，我们可以添加一个 link 来滚动到 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 核心并且未生成 xml，则必须在 .csproj 文件的 PropertyGroup 中添加以下行。

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

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

将描述中的链接添加到 Swagger 中的其他操作（通过 Swashbuckle）

Add links in description to other operations in Swagger (through Swashbuckle)

c#

enums

swagger

swashbuckle