如何使用 Swashbuckle 在生成的 Swagger 文件中生成全局参数？答案

【问题标题】：How to use Swashbuckle to generate global parameters in the resulting Swagger file?如何使用 Swashbuckle 在生成的 Swagger 文件中生成全局参数？
【发布时间】：2020-07-07 19:00:25
【问题描述】：

目前有多种方法可以通过 Swashbuckle 向每个路径添加参数。一些这样的方法可以找到here。

假设我想为每个名为“api-version”的路径添加一个参数。那么这个参数就会出现在Swagger文件的每一个路径中。

我希望 Swashbuckle 生成一个全局参数。例如，而不是这个

{
    "swagger": "2.0",
    "paths": {
      "/something": {
        "post": {
          "operationId": "something_do",
          "parameters": [
            {
              "name": "api-version",
              "in": "query",
              "description": "The API version.",
              "required": true,
              "type": "string"
            }
          ],
          "responses": {
            "200": {
              "description": "Something got done.",
              "schema": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }

，我想要

{
    "swagger": "2.0",
    "paths": {
        "/something": {
            "post": {
                "operationId": "something_do",
                "responses": {
                    "200": {
                        "description": "Something got done.",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        }
    },
    "parameters": {
        "ApiVersionParameter": {
            "name": "api-version",
            "in": "query",
            "required": true,
            "type": "string",
            "description": "The API version."
        }
    }
}

使用全局设置的参数，而不是在每个路径下。我无法在 SwaggerGenOptions 下找到任何产生此内容的内容。

【问题讨论】：

只是为了澄清 - 在全局 parameters 部分（在 OAS2 中）或 components/parameters 部分（在 OAS3 中）中定义的参数 - 就像在您的第二个示例中一样 - 不会自动应用于所有操作。这些参数定义需要在操作中显式 $ref'erenced 才能被实际使用。
您提供的链接使用IOperationFilter，还有IDocumentFilter，您可以修改整个文档...试试这个，如果您遇到问题，请告诉我们

标签： .net swagger swagger-ui swashbuckle swashbuckle.aspnetcore

【解决方案1】：

谢谢赫尔德。 IDocumentFilter 有效。

public class GlobalParameterDocumentFilter : IDocumentFilter
    {
        public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
        {
            if (swaggerDoc != null && swaggerDoc.Components != null)
            {
                swaggerDoc.Components.Parameters.Add(ApiConstants.ApiVersionGlobalParamName, new OpenApiParameter
                {
                    Name = "api-version",
                    In = ParameterLocation.Query,
                    Required = true,
                    Schema = new OpenApiSchema { Type = "string" },
                    Description = "The API version"
                });
            }
        }
    }

然后路径参数可以通过 IOperationFilter 引用这个全局参数。

    public class OperationFilter : IOperationFilter
        {
            public void Apply(OpenApiOperation operation, OperationFilterContext context)
            {
                _ = operation ?? throw new ArgumentNullException(nameof(operation));
                _ = context ?? throw new ArgumentNullException(nameof(context));
    
                if (operation.Parameters == null)
                {
                    operation.Parameters = new List<OpenApiParameter>();
                }
    
                operation.Parameters.Add(
                    new OpenApiParameter
                    {
                        Reference = new OpenApiReference { Id = "parameters/api-version", ExternalResource = "" }
                    });
            }
}

【讨论】：

“ApiVersionGlobalParamName”等于什么？