如何在运行时生成操作文档？

Question

您可以在运行时为操作设置 Swashbuckle 文档吗？

示例：允许的值的文档列表，它基于内部字典，但也可以基于配置。

什么不能解决问题：

• 使用 XML 文档：从代码中的 XML 注释设置文档。这是静态的而不是动态的。
• 使用AddSwaggerGen方法设置全局描述。这是动态的，但处于错误的水平。

Answer 1

使用 ISchemaFilter 你可以做一些疯狂的文档。

这是一个例子：

https://github.com/heldersepu/csharp-proj/blob/master/WebApi_MyGet/WebApi_MyGet/App_Start/SwaggerConfig.cs#L277

Answer 2

有点晚了，但我会添加我是如何做到这一点的。
它依赖于创建一个继承 Swashbuckle 属性的新属性。这是我的示例，它仅处理描述，因为我使用 XML 注释处理其余部分。但添加其他参数是可以扩展的。

我也选择复制文件，但它可以适应使用嵌入式资源。

我的 Markdown 文件位于

<root>/OpenApi/descriptions/*.md

。

using Swashbuckle.AspNetCore.Annotations;

namespace MyApp.OpenAPI;

public class SwaggerDescMdAttribute : SwaggerOperationAttribute
{
    public SwaggerDescMdAttribute(string mdName)
    {
        string filePath = Path.Combine(AppContext.BaseDirectory, "OpenApi", "descriptions", mdName + ".md");
        Description = File.ReadAllText(filePath);
    }
}

然后，考虑到我有一个

Health.md

文件：

...

/// <summary>
/// Check if the API is alive
/// </summary>
/// <response code="200">The API is alive</response>
[SwaggerDescMd("Health")] // <====== THERE
[HttpGet]
[Route("health")]
[ProducesResponseType(StatusCodes.Status200OK)]
public IActionResult GetHeartbeat()
{
    return Ok();
}