将Swagger与命名空间版本的WebApi结合使用 [英] Using Swagger with a namespaced-versioned WebApi

问题描述

我发现了如何使用此类.

我正在使用Swashbuckle，通过Swashbuckle Nuget软件包将Swagger文档添加到我的API中.

I am using Swashbuckle to add Swagger doc to my API, using the Swashbuckle Nuget package.

如果我保持原样，则导航到/swagger/时，我会得到一个空白页面.

If I keep everything intact, when I navigate to /swagger/, I get an empty page.

在我的App_Start中:

In my App_Start:

public class SwaggerConfig
{
    public static void Register()
    {
        Bootstrapper.Init(GlobalConfiguration.Configuration);
        SwaggerSpecConfig.Customize(c =>
            {
                c.IncludeXmlComments(GetXmlCommentsPath());
            });
    }

    private static string GetXmlCommentsPath()
    {
        return string.Format(@"{0}\App_Data\XmlDocumentation.xml", AppDomain.CurrentDomain.BaseDirectory);
    }
}

我的Web API路由:

And my web API routes:

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{namespace}/{controller}/{id}",
            defaults: new
                {
                    id = RouteParameter.Optional
                });
    }
}

如果删除 {namespace} ，它可以工作(显示API命令)，但是我想将此命名空间信息保留在我的路由中.

If I remove the {namespace} it works (the API commands are displayed), but I want to keep this namespace information in my route.

我如何自定义Swagger/Swashbuckle来完成这项工作?

How do I customize Swagger/Swashbuckle to make this work?

推荐答案

来自Swashbuckle Github存储库:

From the Swashbuckle Github repo:

上述命名空间路由"实现中存在一个缺陷，因为它破坏了WebApi元数据层-ApiExplorer并因此破坏了Swashbuckle.

There is a flaw in the above implementation of "namespace routing" as it breaks the WebApi metadata layer - ApiExplorer and hence Swashbuckle.

一种解决方法虽然不能直接解决您的问题，但可以改用属性版本控制，这种方法可以与Swashbuckle配合使用:

A workaround, although doesn't directly solve your problem, is to use attribute versioning instead, which works fine with Swashbuckle:

即:

[RoutePrefix("api/v1/Features")]
public class FeaturesV1Controller : ApiController
{
    [Route("Products/{product}")]
     public IList<Metadata.FeatureListItemModel> Get(long product){}

有关更多信息，请参见下面的两个Github问题. https://github.com/domaindrivendev/Swashbuckle/issues/317 https://github.com/domaindrivendev/Swashbuckle/issues/303

Please see the two Github issues below for more info. https://github.com/domaindrivendev/Swashbuckle/issues/317 https://github.com/domaindrivendev/Swashbuckle/issues/303

我相信使用属性路由时，您的控制器的每个版本都必须使用不同的名称.IE.该类应名为v2的FeaturesV1Controller和FeaturesV2Controller，但是对于路由，您仍然可以使用/api/v1/Features和/api/v2/Features

I believe that with attribute routing, your controller must have a different name for each version. I.e. the class should be named FeaturesV1Controller and FeaturesV2Controller for v2, but for the routes you can still use /api/v1/Features and /api/v2/Features

这篇关于将Swagger与命名空间版本的WebApi结合使用的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！