asp.net-web-api - 使用 Swagger/Swashbuckle 和 OAUTH 的 Web API

Question

我正在尝试让我的 Web API 项目使用 Swagger“漂亮”文档等 ( http://swagger.io/ )

我正在使用 Swashbuckle for .NET，从 NuGet 安装，我使用的版本是 4.0.1

我已经能够安装和使用 Swagger。此时一切看起来都很正常。我遇到的唯一障碍是禁用 API key 并能够使用 OAuth，就像 PetStore 示例 ( http://petstore.swagger.wordnik.com/#!/pet/addPet )

我已经尝试了网上能找到的所有方法。让我在下面列出它们:

首先，这是我的 Startup.cs

public void Configuration(IAppBuilder app)
{
    var config = new HttpConfiguration();

    WebApiConfig.Register(config);

    Swashbuckle.Bootstrapper.Init(config);
}

现在，我的 SwaggerConfig.cs:

public static void Register()
{
    Swashbuckle.Bootstrapper.Init(GlobalConfiguration.Configuration);

    SwaggerSpecConfig.Customize(c =>
    {
        c.IgnoreObsoleteActions();

        c.IncludeXmlComments(GetXmlCommentsPath());

        c.ApiInfo(new Info
        {
            Title = "Work you",
            Description = "testing some stuffs",
            Contact = "Email@email.com"
        });

        c.Authorization("oauth2", new Authorization
        {
            Type = "oauth2",
            Scopes = new List<Scope>
                {
                    new Scope { ScopeId = "products.read", Description = "View products" },
                    new Scope { ScopeId = "products.manage", Description = "Manage products" }
                },
            GrantTypes = new GrantTypes
            {
                ImplicitGrant = new ImplicitGrant
                {
                    LoginEndpoint = new LoginEndpoint
                    {
                        Url = "https://www.mysecure.website.com"
                    },
                    TokenName = "access_token"
                }
            }
        });
    });


    SwaggerUiConfig.Customize(c =>
    {
        c.EnableOAuth2Support("client_id", "test-realm", "app Name");

        var thisAssembly = typeof(SwaggerConfig).Assembly;

        c.SupportHeaderParams = true;
        c.DocExpansion = DocExpansion.List;
        c.SupportedSubmitMethods = new[] { HttpMethod.Get, HttpMethod.Post, HttpMethod.Put, HttpMethod.Head };
        c.EnableDiscoveryUrlSelector();

    });

}

我有一个 SwaggerExtensions 文件夹，其中有需要的文件。例如:

我的类(class)装饰有:

[ScopeAuthorize("this.scope")]

但是，OAuth 选项永远不会在 swagger 页面上显示。我也看不到应该在哪里输入自定义 header 。

我确实看到标题和文档描述、电子邮件地址等正在从 SwaggerConfig.cs 中读取，因此我知道它至少已被读取。

我想不通。 :(

有什么想法吗？

Answer 1

我得到了我的解决方案。这很强大，只是不是 100% 直接配置。

以下是我采取的步骤:

安装 NuGet 包，我使用 PM> Install-Package Swashbuckle -Version 4.1.0 但链接位于 https://www.nuget.org/packages/Swashbuckle/我建议获取最新版本，但我知道 4.1.0 有效。 编辑 我刚刚更新到 5.X，但它破坏了它。 4.1.0 可以工作，但最新的不行。我还没有进一步研究原因。

一旦你安装了这个，你就差不多完成了。

安装将创建一个 SwaggerConfig.cs 文件。这是我使用的代码(从github master复制)

public class SwaggerConfig
    {
        public static void Register()
        {
            Swashbuckle.Bootstrapper.Init(GlobalConfiguration.Configuration);

            SwaggerSpecConfig.Customize(c =>
            {
                c.IgnoreObsoleteActions();

                //c.SupportMultipleApiVersions(
                //    new[] { "1.0", "2.0" },
                //    ResolveVersionSupportByRouteConstraint);

                //c.PolymorphicType<Animal>(ac => ac
                //    .DiscriminateBy(a => a.Type)
                //    .SubType<Kitten>());

                c.OperationFilter<AddStandardResponseCodes>();
                c.OperationFilter<AddAuthResponseCodes>();
                c.OperationFilter<AddOAuth2Scopes>();

                //c.IncludeXmlComments(GetXmlCommentsPath());

                c.ApiInfo(new Info
                {
                    Title = "Swashbuckle Dummy",
                    Description = "For testing and experimenting with Swashbuckle features",
                    Contact = "someone@somewhere.com"
                });

                c.Authorization("oauth2", new Authorization
                {
                    Type = "oauth2",
                    Scopes = new List<Scope>
                        {
                            new Scope { ScopeId = "test1", Description = "test1" },
                            new Scope { ScopeId = "test2", Description = "test2" }
                        },
                    GrantTypes = new GrantTypes
                    {
                        ImplicitGrant = new ImplicitGrant
                        {
                            LoginEndpoint = new LoginEndpoint
                            {
                                Url = "https://your.Oauth.server/Authorize"
                            },
                            TokenName = "access_token"
                        }
                    }
                });
            });

            SwaggerUiConfig.Customize(c =>
            {
                var thisAssembly = typeof(SwaggerConfig).Assembly;

                c.SupportHeaderParams = true;
                c.DocExpansion = DocExpansion.List;
                c.SupportedSubmitMethods = new[] { HttpMethod.Get, HttpMethod.Post, HttpMethod.Put, HttpMethod.Head };
                //c.InjectJavaScript(typeof(SwaggerConfig).Assembly, "WebApplication4.SwaggerExtensions.onComplete.js");
                //c.EnableDiscoveryUrlSelector();
                //c.InjectJavaScript(thisAssembly, "Swashbuckle.Dummy.SwaggerExtensions.testScript1.js");
                //c.InjectStylesheet(thisAssembly, "Swashbuckle.Dummy.SwaggerExtensions.testStyles1.css");

                c.EnableOAuth2Support("client_id", "realm", "Swagger UI");
            });
            // NOTE: If you want to customize the generated swagger or UI, use SwaggerSpecConfig and/or SwaggerUiConfig here ...
        }
        private static string GetXmlCommentsPath()
        {
            return String.Format(@"{0}\XmlComments.xml", AppDomain.CurrentDomain.BaseDirectory);
        }

现在我们已经告诉 Swagger 我们想要使用 OAuth，这就是我们想要使用它的方式。完成了，对吧？不。

您需要将此文件夹和文件添加到您的解决方案中:https://github.com/domaindrivendev/Swashbuckle/tree/master/Swashbuckle.Dummy.Core/SwaggerExtensions

(您只需要 .cs 文件)

确保您的命名空间正确...

然后，您需要在 WebAPI 中修饰您的类，如下所示:

[ScopeAuthorize("test1")]

现在，当您运行它并进入 swagger 页面时，您将看到具有该声明的每个操作在右上角都会有 OAuth 开关。当您单击它时，您可以使用隐式授权流程并获取将添加到您的请求中的 token 。

这只适用于我发现的隐式授权。他们似乎确实试图让 AuthorizationCode Grant 继续下去，但他们构建的 js 文件仅支持隐式的支持。

希望这对某人有帮助。这是一个强大的工具，我希望我们看到更多的网站使用这样的工具。

谢谢，祝你好运!