Использование Swagger с WebApi с версией пространства имен

Question

Я узнал, как создать версию моего WebAPI на основе пространств имен, используя этот класс.

Я использую Swashbuckle для добавления документа Swagger в мой API с помощью пакета Swashbuckle Nuget.

Если я сохраню все в порядке, при переходе к / swagger / я получаю пустую страницу.

В моем 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);
    }
}

И мои маршруты веб-API:

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), но я хочу сохранить эту информацию о пространстве имен в моем маршруте.

Как мне настроить Swagger/Swashbuckle, чтобы эта работа работала?

Answer 1

Из репозитория Swashbuckle Github:

В приведенной выше реализации "маршрутизации пространства имен" есть недостаток, поскольку он нарушает уровень метаданных WebApi - ApiExplorer и, следовательно, Swashbuckle.

Обходной путь, хотя и не решающий вашу проблему напрямую, - вместо этого использовать управление версиями атрибутов, что прекрасно работает с 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

Я считаю, что с атрибутом маршрутизации, ваш контроллер должен иметь разные имена для каждой версии. Т.е. класс должен называться FeaturesV1Controller и FeaturesV2Controller для v2, но для маршрутов вы все равно можете использовать /api/v1/Features и /api/v2/Features