如何使用 Swashbuckle 在生成的 Swagger 文件中生成全局参数? [英] How to use Swashbuckle to generate global parameters in the resulting Swagger file?

问题描述

目前有多种方法可以通过 Swashbuckle 向每条路径添加参数.可以找到一些这样的方式 这里.

There are currently ways to add parameters to every path via Swashbuckle. Some such way can be found here.

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

Let's say I want to add a parameter to every path called 'api-version'. Then this parameter will appear in every path in the Swagger file.

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

I want Swashbuckle to generate a single global parameter. For example, instead of this

{
    "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 下找到任何产生这种情况的内容.

with the parameter set globally, and not under every path. I'm unable to find anything under SwaggerGenOptions that produces this.

推荐答案

谢谢 Helder.IDocumentFilter 有效.

Thank you Helder. The IDocumentFilter works.

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 引用这个全局参数.

The path parameter can then reference this global parameter via an 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 = "" }
                    });
            }
}

这篇关于如何使用 Swashbuckle 在生成的 Swagger 文件中生成全局参数?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！