NSwag: создание клиента C # из нескольких версий API - PullRequest
Новая
       230

NSwag: создание клиента C # из нескольких версий API

0 голосов
/ 30 мая 2018

Мы создаем версию нашего API и генерируем спецификацию Swagger с использованием Swashbuckle в ASP.NET Core 1.1.Мы можем создать два документа API на основе этих файлов спецификации JSON: 

<!-- language: c# -->
services.AddSwaggerGen(setupAction =>
{
    setupAction.SwaggerDoc("0.1", new Info { Title = "Api", Version = "0.1", Description = "API v0.1" });
    setupAction.SwaggerDoc("0.2", new Info { Title = "Api", Version = "0.2", Description = "API v0.2" });

    // more configuration omitted
}

Мы включаем все действия в оба файла спецификации, если только они не сопоставлены с конкретной версией с использованием атрибутов [MapToApiVersion] и ApiExplorerSettings(GroupName ="<version>")],Методы, принадлежащие только к более старой версии, также украшены атрибутом [Obsolete]: 

<!-- language: c# -->
[MapToApiVersion("0.1")]
[ApiExplorerSettings(GroupName = "0.1")]
[Obsolete]

Однако мы хотим, чтобы только один клиент C # генерировался из объединения обоих файлов спецификаций, где включены все методыв клиенте 0.1 и 0.2, но все устаревшие методы помечены как устаревшие.

Я рассмотрел как NSwag (который мы используем довольно давно), так и AutoRest.Кажется, что AutoRest поддерживает сценарий объединения , но я не смог заставить его работать из-за ошибок проверки схемы (и я более чем уверен, будет ли наш конкретный сценарий фактически поддерживаться).

Моя последняя идея на данный момент получить эту сортировку - каким-то образом JSON-объединить спецификации в одну и затем передать их NSwag.

Мы что-то здесь упускаем?Можно ли это как-то реализовать с помощью NSwag?

Ответы [ 2 ]

0 голосов
/ 01 июля 2018

Пакеты:

Install-Package Swashbuckle.AspNetCore

Install-пакет Microsoft.AspNetCore.Mvc.Versioning

enter image description here

ValueV1Controller.cs 

[ApiVersion("1")]
[Route("api/v{version:apiVersion}/Values")]
public class ValuesV1Controller : Controller
{
    // GET api/values
    [HttpGet]
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }
}

ValueV2Controller.cs 

[ApiVersion("2")]
[Route("api/v{version:apiVersion}/Values")]
public class ValuesV2Controller : Controller
{
    // GET api/values
    [HttpGet]
    public IEnumerable<string> Get()
    {
        return new string[] { "value1.2", "value2.2" };
    }
}

Запуск.cs 

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();
        services.AddApiVersioning();
        // Register the Swagger generator, defining 1 or more Swagger documents
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new Info { Title = "My API - V1", Version = "v1" });
            c.SwaggerDoc("v2", new Info { Title = "My API - V2", Version = "v2" });

            c.DocInclusionPredicate((docName, apiDesc) =>
            {
                var versions = apiDesc.ControllerAttributes()
                    .OfType<ApiVersionAttribute>()
                    .SelectMany(attr => attr.Versions);

                return versions.Any(v => $"v{v.ToString()}" == docName);
            });

            c.OperationFilter<RemoveVersionParameters>();
            c.DocumentFilter<SetVersionInPaths>();
        });
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();

        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
        // specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });

        app.UseMvc();
    }
}

public class RemoveVersionParameters : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        var versionParameter = operation.Parameters?.SingleOrDefault(p => p.Name == "version");
        if (versionParameter != null)
            operation.Parameters.Remove(versionParameter);
    }
}

public class SetVersionInPaths : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        swaggerDoc.Paths = swaggerDoc.Paths
            .ToDictionary(
                path => path.Key.Replace("v{version}", swaggerDoc.Info.Version),
                path => path.Value
            );
    }
}
0 голосов
/ 01 июня 2018

Вот моя идея, расширяющаяся от комментариев:

С помощью swashbuckle вы можете сгенерировать столько SwaggerDoc, сколько захотите, идея в этом случае - сгенерировать 3, сохранить те же 2 версии, которые у вас есть, и добавитьеще один, который будет иметь все.

c.MultipleApiVersions(
    (apiDesc, targetApiVersion) => 
      targetApiVersion.Equals("default") || // Include everything by default
      apiDesc.Route.RouteTemplate.StartsWith(targetApiVersion), // Only include matching routes for other versions
    (vc) =>
    {
        vc.Version("default", "Swagger_Test");
        vc.Version("v1_0", "Swagger_Test V1_0");
        vc.Version("v2_0", "Swagger_Test V2_0");
    });

Вот рабочий пример:
http://swagger -net-test-multiapiversions.azurewebsites.net / swagger / ui / index? Filter = Api

И весь код этого проекта находится на GitHub:
https://github.com/heldersepu/Swagger-Net-Test/tree/MultiApiVersions

...