如何在ASP.NET Web API的Swagger UI中手动添加OAuth令牌端点

没问题，我来帮你搞定把OWIN配置的OAuth令牌端点手动加到Swagger UI里的事儿！因为Swagger确实没法自动识别这个非API控制器的端点，咱们得用自定义过滤器来注入元数据，具体步骤如下：

1. 创建自定义Swagger文档过滤器 #

首先，我们需要实现IDocumentFilter接口，在这个过滤器里手动把/token端点的元数据添加到Swagger文档中。这个过滤器会在Swagger生成文档时被调用，让我们可以自定义文档内容。

using Swashbuckle.Swagger;
using System.Collections.Generic;
using System.Web.Http.Description;

public class OAuthTokenEndpointFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
    {
        // 添加/token POST端点
        swaggerDoc.Paths.Add("/token", new PathItem
        {
            Post = new Operation
            {
                Tags = new List<string> { "Authentication" },
                Summary = "获取OAuth2访问令牌",
                Description = "通过用户名密码、刷新令牌等授权类型获取访问令牌",
                Consumes = new List<string> { "application/x-www-form-urlencoded" },
                Produces = new List<string> { "application/json" },
                Parameters = new List<Parameter>
                {
                    new Parameter
                    {
                        Name = "grant_type",
                        In = "formData",
                        Required = true,
                        Type = "string",
                        Description = "授权类型，支持password、refresh_token等（根据你的OAuth配置调整）"
                    },
                    new Parameter
                    {
                        Name = "username",
                        In = "formData",
                        Required = false,
                        Type = "string",
                        Description = "用户名（当grant_type为password时必填）"
                    },
                    new Parameter
                    {
                        Name = "password",
                        In = "formData",
                        Required = false,
                        Type = "string",
                        Description = "密码（当grant_type为password时必填）"
                    },
                    new Parameter
                    {
                        Name = "refresh_token",
                        In = "formData",
                        Required = false,
                        Type = "string",
                        Description = "刷新令牌（当grant_type为refresh_token时必填）"
                    }
                },
                Responses = new Dictionary<string, Response>
                {
                    { "200", new Response { Description = "成功获取令牌", Schema = schemaRegistry.GetOrRegister(typeof(TokenResponse)) } },
                    { "400", new Response { Description = "请求参数错误或不合法" } },
                    { "401", new Response { Description = "身份验证失败，用户名/密码错误或权限不足" } }
                }
            }
        });
    }
}

// 定义令牌响应模型，要和你的OAuth端点实际返回的结构一致
public class TokenResponse
{
    public string access_token { get; set; }
    public string token_type { get; set; }
    public int expires_in { get; set; }
    public string refresh_token { get; set; }
    // 如果你的端点返回其他字段，比如userName，也可以在这里添加
}

2. 将过滤器注册到Swagger配置 #

找到你的Swagger配置文件（通常是SwaggerConfig.cs），在启用Swagger的代码中添加这个自定义过滤器：

public class SwaggerConfig
{
    public static void Register()
    {
        var thisAssembly = typeof(SwaggerConfig).Assembly;

        GlobalConfiguration.Configuration
            .EnableSwagger(c =>
            {
                c.SingleApiVersion("v1", "你的API名称");
                
                // 注册自定义的OAuth令牌端点过滤器
                c.DocumentFilter<OAuthTokenEndpointFilter>();

                // 配置OAuth2授权信息，让Swagger UI知道如何获取令牌
                c.OAuth2("oauth2")
                    .Description("OAuth2密码模式授权")
                    .Flow("password") // 这里要和你的OAuth配置的授权流程一致，比如password/implicit等
                    .TokenUrl("/token") // 指向你的OAuth令牌端点
                    .Scopes(scopes =>
                    {
                        scopes.Add("api", "访问API的基础权限");
                        // 如果你的API有细分权限，也可以在这里添加更多scope
                    });
            })
            .EnableSwaggerUi(c =>
            {
                // 启用Swagger UI的OAuth2支持，让用户可以直接在UI里获取令牌
                c.EnableOAuth2Support(
                    clientId: "你的客户端ID", // 对应OAuthAuthorizationServerOptions中的ClientId
                    clientSecret: "你的客户端密钥", // 对应OAuthAuthorizationServerOptions中的ClientSecret（如果配置了的话）
                    realm: "你的API领域", // 对应OAuthAuthorizationServerOptions中的Realm
                    appName: "Swagger UI",
                    additionalQueryStringParams: new Dictionary<string, string>());
            });
    }
}

3. 调整细节适配你的实际配置 #

• 确保TokenResponse类的字段和你的OAuth端点实际返回的JSON结构完全一致，这样Swagger才能正确显示响应示例。
• 如果你的OAuth端点支持其他授权类型（比如client_credentials），可以在过滤器的Parameters里添加对应的参数（比如client_id、client_secret）。
• 客户端ID、密钥、领域这些参数要和你在OAuthAuthorizationServerOptions里配置的保持一致，否则Swagger UI的授权流程会失败。

完成这些步骤后，重启你的API项目，打开Swagger UI就能看到Authentication标签下的/token端点了，而且还能直接在Swagger里发起令牌请求，获取到令牌后自动附加到后续的API调用中，非常方便！

内容的提问来源于stack exchange，提问作者Victor Mukherjee