如何在 Swagger 中显示 WebApi OAuth 令牌端点答案

【问题标题】：How to show WebApi OAuth token endpoint in Swagger如何在 Swagger 中显示 WebApi OAuth 令牌端点
【发布时间】：2019-06-15 01:33:44
【问题描述】：

我创建了一个新的 Web Api 项目，添加了 Asp.Net Identity 并像这样配置了 OAuth：

OAuthOptions = new OAuthAuthorizationServerOptions
{
    TokenEndpointPath = new PathString("/Token"),
    Provider = new ApplicationOAuthProvider(PublicClientId),
    AuthorizeEndpointPath = new PathString("/api/Account/ExternalLogin"),
    AccessTokenExpireTimeSpan = TimeSpan.FromDays(14),
    AllowInsecureHttp = true
};

这一切正常，我可以调用 /Token 端点并取回不记名令牌。

问题是我认为这在 Swagger 中是不可发现的，因为它不在控制器上，因此没有为它生成 xml 文档。

有人知道在我的 Swagger 文档中显示此登录端点的方法吗？

谢谢。

另外，我应该说 Swagger 文档适用于我所有的控制器，只是我缺少一个明显的方法 - 如何登录。

【问题讨论】：

我不知道这个Link 是否会有所帮助，但它也会解释如何在没有任何人的情况下创建 XML
谢谢，这实际上是我设置 Swagger 时关注的文章之一。
您在标签中提到了 Swashbuckle，您是否看过 github.com/domaindrivendev/Swashbuckle/blob/master/README.md 的“描述安全/授权方案”部分？
是的，通过 swashbuckle - 我已经为 oauth 隐式工作流配置了 swagger，这使得 swagger UI 能够执行 post/get 请求等。我不相信这个配置会创建任何 api 文档令牌端点。

标签： asp.net-web-api asp.net-identity swagger-ui swashbuckle

【解决方案1】：

ApiExplorer 不会自动为您的端点生成任何信息，因此您需要添加自定义 DocumentFilter 才能手动描述令牌端点。

https://github.com/domaindrivendev/Swashbuckle/issues/332 有一个例子：

class AuthTokenOperation : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
    {
        swaggerDoc.paths.Add("/auth/token", new PathItem
        {
            post = new Operation
            {
                tags = new List<string> { "Auth" },
                consumes = new List<string>
                {
                    "application/x-www-form-urlencoded"
                },
                parameters = new List<Parameter> {
                    new Parameter
                    {
                        type = "string",
                        name = "grant_type",
                        required = true,
                        @in = "formData"
                    },
                    new Parameter
                    {
                        type = "string",
                        name = "username",
                        required = false,
                        @in = "formData"
                    },
                    new Parameter
                    {
                        type = "string",
                        name = "password",
                        required = false,
                        @in = "formData"
                    }
                }
            }
        });
    }
}

httpConfig.EnableSwagger(c =>
{
    c.DocumentFilter<AuthTokenOperation>();
});

【讨论】：

我们需要把这个类放在哪里才能让 HelpPage 生成器创建正确的 html ？
@EeKay：最有可能在您的 SwaggerConfig.cs 中 - 这是上面代码示例中的最后一部分 (httpConfig.EnableSwagger(...))
有没有办法标记密码字段，以便在 Try It 部分输入时显示 ******* 而不是密码？
OK 找到了 - 在 Parameter 对象上设置 format = "password"。谢谢。
@user230910：是的，它正在使用 Swashbuckle.Swagger

【解决方案2】：

如果有人想知道如何向此操作添加响应正文，这里是更新后的 Ruaidhri 代码：

class AuthTokenOperation : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
    {
        swaggerDoc.paths.Add("/token", new PathItem
        {
            post = new Operation
            {
                tags = new List<string> { "Auth" },
                consumes = new List<string>
                    {
                        "application/x-www-form-urlencoded"
                    },
                parameters = new List<Parameter> {
                    new Parameter
                    {
                        type = "string",
                        name = "grant_type",
                        required = true,
                        @in = "formData"
                    },
                    new Parameter
                    {
                        type = "string",
                        name = "username",
                        required = false,
                        @in = "formData"
                    },
                    new Parameter
                    {
                        type = "string",
                        name = "password",
                        required = false,
                        @in = "formData"
                    }
                },
                responses = new Dictionary<string, Response>()
                {
                    {
                        "200",
                        new Response {schema = schemaRegistry.GetOrRegister(typeof(OAuthTokenResponse))}
                    }
                }
            }
        });
    }
}

class OAuthTokenResponse
{
    [JsonProperty("access_token")]
    public string AccessToken { get; set; }

    [JsonProperty("token_type")]
    public string TokenType { get; set; }

    [JsonProperty("expires_in")]
    public long ExpiresIn { get; set; }

    [JsonProperty("userName")]
    public string Username { get; set; }

    [JsonProperty(".issued")]
    public DateTime Issued { get; set; }

    [JsonProperty(".expires")]
    public DateTime Expires { get; set; }
}

【讨论】：