Question

根据documentation for Swashbuckle，最新版本仅支持少量XML注释。似乎目前不支持<example>或<see>等XML评论but will be implemented in Swashbuckle v6。

在此之前，我是否有办法解决<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

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

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

1 个答案: