web-dev-qa-db-ja.com

NSwag .NET Core APIバージョン管理構成

RESTサービス標準に従って、APIの複数のバージョンを管理および文書化できるように、。NET Core Web APIプロジェクトを準備したいと思います。

。NET Core 2.1とNSwag（v11.18.2）を使用しています。 Microsoft.AspNetCore.Mvc.VersioningNuGetパッケージもインストールしました。

すでにいくつかの設定例をGoogleで検索しましたが、見つかった唯一の便利なリンクは this です。

両方のAPIバージョンのSwaggerページを取得できるようになりましたが、いくつか問題があります。

  1. 最後のconfig設定（Title、Descriptionなど）は、2つのルートのいずれにも影響しないことに注意してください。個々の構成のそれぞれに追加した場合にのみ機能します。 APIの一般的な構成はバージョンに依存しない可能性があるため（タイトル、説明など...）、それを回避できるかどうかも知りたいです。
  2. 上記のリンクで説明されているNSwagおよびMicrosoft APIバージョン管理パッケージの問題は2〜3か月前（およびNSwagバージョンも）に公開されているため、これが本当に修正されているかどうかを確認したいと思います。設定する正しい構成。
  3. バージョンはコントローラーの構成で明示的ですが、コントローラーメソッドの必須の入力パラメーターとして必要であり、もちろんそれは望みません！画像を見る：

Swagger UI tests requiring version as input parameter for methods

したがって、その例に従う私の実際の構成は次のようになります。

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddApiVersioning(options =>
        {
            options.AssumeDefaultVersionWhenUnspecified = true;
            options.DefaultApiVersion = new ApiVersion(1, 0);
            options.ReportApiVersions = true;
        });
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseSwaggerWithApiExplorer(config =>
    {
        config.GeneratorSettings.OperationProcessors.TryGet<ApiVersionProcessor>().IncludedVersions = new[] { "1.0" };
        config.SwaggerRoute = "v1.0.json";
    });

    app.UseSwaggerWithApiExplorer(config =>
    {
        config.GeneratorSettings.OperationProcessors.TryGet<ApiVersionProcessor>().IncludedVersions = new[] { "2.0" };
        config.SwaggerRoute = "v2.0.json";
    });

    app.UseSwaggerUi3(typeof(Startup).GetTypeInfo().Assembly, config =>
    {
        config.SwaggerRoutes.Add(new SwaggerUi3Route("v1.0", "/v1.0.json"));
        config.SwaggerRoutes.Add(new SwaggerUi3Route("v2.0", "/v2.0.json"));

        config.GeneratorSettings.Title = "My API";
        config.GeneratorSettings.Description = "API functionalities.";
        config.GeneratorSettings.DefaultUrlTemplate = "{v:apiVersion}/{controller}/{action}/{id?}";
        config.GeneratorSettings.DefaultPropertyNameHandling = PropertyNameHandling.CamelCase
    });
}

そして、これらは私の実際のコントローラーです：

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]/[action]")]
[SwaggerTag("Test1", Description = "Core operations on machines (v1.0).")]
public class MachinesController : Controller
{
    [HttpGet("{id}")]
    [ProducesResponseType((int)HttpStatusCode.OK)]
    public async Task<ActionResult<Machine>> Get(int id)
    {
        return await ...
    }
}

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]/[action]")]
[SwaggerTag("Test2", Description = "Core operations on machines (v2.0).")]
public class MachinesController : Controller
{
    [HttpGet("{id}")]
    [ProducesResponseType((int)HttpStatusCode.OK)]
    public async Task<ActionResult<Machine>> Get(int id)
    {
        return await ...
    }
}
c#.net-coreasp.net-core-webapiapi-versioningnswag
7
Cheshire Cat
  1. これらは設定から​​推測されるか、API Explorer（テンプレート）に適用されないため、ミドルウェアでは無視されます。ただし、タイトルと説明は機能するはずです...
  2. 特定の問題と再現を含む問題を作成してください。また、リポジトリ内の既存のテストを確認してください
  3. V11.18.3で修正
2
Rico Suter

NSwag 12.0.0以降、API Explorerのサポートが大幅に改善されたと思います。 NSwagに適切な情報が提供されるように、補足的な APIバージョン管理用のAPI Explorerパッケージ も参照されることが重要です。

APIバージョニングによって提供される Swaggerサンプルアプリケーション はSwashbuckleを使用しますが、設定はNSwagと非常に似ています。 IApiVersionDescriptionProviderサービスを使用して、アプリケーションで定義されているすべてのAPIバージョンを列挙できます。これにより、NSwag構成が大幅に簡素化されます。

URLセグメントごとにバージョン管理しています。したがって、問題を解決するには、3 API Explorer a laを設定するだけです：

services.AddVersionedApiExplorer( options => options.SubstituteApiVersionInUrl = true );

これは{version}ルートテンプレートのルートパラメータと対応するAPIバージョン値を使用して、APIバージョンパラメータをAPIの説明から削除します。

1
Chris Martinez