NSwag中Swagger UI参数数据类型显示问题的解决方案

问题背景

在使用NSwag生成API文档时，开发者可能会遇到Swagger UI界面无法正确显示端点参数数据类型的问题。这种情况通常表现为参数类型信息缺失，导致API文档不够清晰完整。

问题分析

通过检查生成的OpenAPI/Swagger JSON文档，可以发现参数定义中虽然包含了type字段（如integer），但缺少了Swagger UI所需的schema部分。Swagger UI依赖于schema来正确显示参数的数据类型信息。

解决方案

基本解决思路

我们可以通过实现一个自定义的IOperationProcessor来为每个参数添加schema信息。这个处理器会在文档生成过程中被调用，允许我们修改参数定义。

实现代码

using NSwag;
using NSwag.Generation.Processors;
using NSwag.Generation.Processors.Contexts;

namespace SI.NonTrade.WebApi;

internal class DocCardsOperationProcessor : IOperationProcessor
{
    public bool Process(OperationProcessorContext context)
    {
        IList<OpenApiParameter> apiParameters = context.OperationDescription.Operation.Parameters;
        foreach (OpenApiParameter apiParameter in apiParameters)
        {
            apiParameter.Schema = new()
            {
                Type = apiParameter.Type,
                Format = apiParameter.Format,
                IsNullableRaw = apiParameter.IsNullableRaw
            };
        }

        return true;
    }
}

代码解析

1. 处理器注册：这个类实现了IOperationProcessor接口，可以在NSwag配置中注册使用。

2. 参数处理：遍历操作中的所有参数，为每个参数创建并设置schema对象。

3. 属性映射：

   • Type：从参数直接映射类型
   • Format：保留原有的格式信息
   • IsNullableRaw：保持原有的可空性设置

4. 返回值：返回true表示处理成功，文档生成过程可以继续。

使用说明

1. 将上述处理器类添加到项目中。

2. 在NSwag配置中添加处理器：

services.AddOpenApiDocument(config =>
{
    config.OperationProcessors.Add(new DocCardsOperationProcessor());
    // 其他配置...
});

3. 重新生成API文档，Swagger UI现在应该能够正确显示参数数据类型了。

注意事项

1. 这个解决方案适用于简单类型参数（如int、string等）和复杂类型参数。

2. 对于复杂类型（如[FromQuery] MyRequest类参数），处理器会自动处理其内部结构。

3. 如果API文档有其他特殊需求，可以在此基础上扩展处理器功能。

总结

通过实现自定义的IOperationProcessor，我们能够灵活地修改生成的OpenAPI文档，解决Swagger UI中参数数据类型显示不完整的问题。这种方法不仅解决了当前问题，还为未来可能的文档定制需求提供了扩展点。