SwashbuckleとMicrosoft.AspNetCore.Mvc.Versioningのセットアップ方法
Asp.netコアwebapiがあります。 Microsoft.AspNetCore.Mvc.VersioningとSwashbuckleを追加して、UIをSwaggerにしました。コントローラを次のように指定しました：
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ContactController : Controller
{
Swagger uiを実行すると、ルートのパラメーターとしてバージョンが取得されます。 
ルートのデフォルト「v1」を設定するにはどうすればよいですか？バージョン2が登場した場合、両方のバージョンでSwagger uiをどのようにサポートしますか？
現在、SwashbuckleとMicrosoft.AspNetCore.Mvc.Versioningは友だちです。それはうまくいきます。 VS2017でテストプロジェクトを作成し、その動作を確認しました。
まず、次の2つのnugetパッケージを含めます。
<PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning" Version="1.2.1" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="1.0.0" />
Startup.cs（私のコメントを読む）：
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
// Configure versions
services.AddApiVersioning(o =>
{
o.AssumeDefaultVersionWhenUnspecified = true;
o.DefaultApiVersion = new ApiVersion(1, 0);
});
// Configure swagger
services.AddSwaggerGen(options =>
{
// Specify two versions
options.SwaggerDoc("v1",
new Info()
{
Version = "v1",
Title = "v1 API",
Description = "v1 API Description",
TermsOfService = "Terms of usage v1"
});
options.SwaggerDoc("v2",
new Info()
{
Version = "v2",
Title = "v2 API",
Description = "v2 API Description",
TermsOfService = "Terms of usage v2"
});
// This call remove version from parameter, without it we will have version as parameter
// for all endpoints in swagger UI
options.OperationFilter<RemoveVersionFromParameter>();
// This make replacement of v{version:apiVersion} to real version of corresponding swagger doc.
options.DocumentFilter<ReplaceVersionWithExactValueInPath>();
// This on used to exclude endpoint mapped to not specified in swagger version.
// In this particular example we exclude 'GET /api/v2/Values/otherget/three' endpoint,
// because it was mapped to v3 with attribute: MapToApiVersion("3")
options.DocInclusionPredicate((version, desc) =>
{
var versions = desc.ControllerAttributes()
.OfType<ApiVersionAttribute>()
.SelectMany(attr => attr.Versions);
var maps = desc.ActionAttributes()
.OfType<MapToApiVersionAttribute>()
.SelectMany(attr => attr.Versions)
.ToArray();
return versions.Any(v => $"v{v.ToString()}" == version) && (maps.Length == 0 || maps.Any(v => $"v{v.ToString()}" == version));
});
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
loggerFactory.AddConsole(Configuration.GetSection("Logging"));
loggerFactory.AddDebug();
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint($"/swagger/v2/swagger.json", $"v2");
c.SwaggerEndpoint($"/swagger/v1/swagger.json", $"v1");
});
app.UseMvc();
}
トリックを作る2つのクラスがあります：
public class RemoveVersionFromParameter : IOperationFilter
{
public void Apply(Operation operation, OperationFilterContext context)
{
var versionParameter = operation.Parameters.Single(p => p.Name == "version");
operation.Parameters.Remove(versionParameter);
}
}
public class ReplaceVersionWithExactValueInPath : 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
);
}
}
RemoveVersionFromParameterは、このテキストボックスをswagger UIから削除します。
ReplaceVersionWithExactValueInPathはこれを変更します：
これに：
コントローラクラスは次のようになります。
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1")]
[ApiVersion("2")]
public class ValuesController : Controller
{
// GET api/values
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
// GET api/values/5
[HttpGet("{id}")]
public string Get(int id)
{
return "value";
}
// POST api/values
[HttpPost]
public void Post([FromBody]string value)
{
}
// PUT api/values/5
[HttpPut("{id}")]
public void Put(int id, [FromBody]string value)
{
}
// DELETE api/values/5
[HttpDelete("{id}")]
public void Delete(int id)
{
}
[HttpGet("otherget/one")]
[MapToApiVersion("2")]
public IEnumerable<string> Get2()
{
return new string[] { "value1", "value2" };
}
/// <summary>
/// THIS ONE WILL BE EXCLUDED FROM SWAGGER Ui, BECAUSE v3 IS NOT SPECIFIED. 'DocInclusionPredicate' MAKES THE
/// TRICK
/// </summary>
/// <returns></returns>
[HttpGet("otherget/three")]
[MapToApiVersion("3")]
public IEnumerable<string> Get3()
{
return new string[] { "value1", "value2" };
}
}
コード： https://Gist.github.com/Alezis/bab8b559d0d8800c994d065db03ab53e
.net core 3に更新すると、次のエラーが発生しました。
'タイプ' System.Collections.Generic.Dictionary`2 [System.String、Microsoft.OpenApi.Models.OpenApiPathItem] 'のオブジェクトを' Microsoft.OpenApi.Models.OpenApiPaths '。'にキャストできません。 ' =
これを修正するには、コードを次のように変更します。
public class ReplaceVersionWithExactValueInPath : IDocumentFilter
{
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
if (swaggerDoc == null)
throw new ArgumentNullException(nameof(swaggerDoc));
var replacements = new OpenApiPaths();
foreach (var (key, value) in swaggerDoc.Paths)
{
replacements.Add(key.Replace("{version}", swaggerDoc.Info.Version, StringComparison.InvariantCulture), value);
}
swaggerDoc.Paths = replacements;
}
}
@Alezisナイスなアプローチですが、Microsoft.AspNetCore.Mvc.Versioning（2.3.0）ライブラリの最新バージョンを使用している場合、ControllerAttributes()およびActionAttributes()は非推奨です。更新できますDocInclusionPredicate次のように：
options.DocInclusionPredicate((version, desc) =>
{
if (!desc.TryGetMethodInfo(out MethodInfo methodInfo)) return false;
var versions = methodInfo.DeclaringType
.GetCustomAttributes(true)
.OfType<ApiVersionAttribute>()
.SelectMany(attr => attr.Versions);
return versions.Any(v => $"v{v.ToString()}" == version);
});
Swashbuckle.AspNetCore githubプロジェクトは非常に役立ちます。
.Net Core 3で作業している場合、基本的に私は@Alezisのソリューションを採用し、.Net Core 3で動作するように更新しました。
public void ConfigureServices(IServiceCollection services)
{
....
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo() { Title = "My API", Version = "v1" });
options.OperationFilter<RemoveVersionFromParameter>();
options.DocumentFilter<ReplaceVersionWithExactValueInPath>();
});
...
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
...
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
...
}
public class RemoveVersionFromParameter : IOperationFilter
{
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
var versionParameter = operation.Parameters.Single(p => p.Name == "version");
operation.Parameters.Remove(versionParameter);
}
}
public class ReplaceVersionWithExactValueInPath : IDocumentFilter
{
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
var paths = new OpenApiPaths();
foreach (var path in swaggerDoc.Paths)
{
paths.Add(path.Key.Replace("v{version}", swaggerDoc.Info.Version), path.Value);
}
swaggerDoc.Paths = paths;
}
}
OpenAPIドキュメントを調整する代わりに、APIエクスプローラーにバージョンを追加するMicrosoft提供のライブラリを使用できます。これにより、Swashbuckle（または別のツールチェーン）がバージョンを必要とする前にバージョンが提供され、カスタムコードを回避できます。
Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
パッケージとこのコードブロックを追加した後、バージョンを正しく構成することができました。
services.AddVersionedApiExplorer(
options =>
{
// add the versioned api Explorer, which also adds IApiVersionDescriptionProvider service
// note: the specified format code will format the version as "'v'major[.minor][-status]"
options.GroupNameFormat = "'v'VVV";
// note: this option is only necessary when versioning by url segment. the SubstitutionFormat
// can also be used to control the format of the API version in route templates
options.SubstituteApiVersionInUrl = true;
}
);
ArlanGが強調表示した方法 を使用すると{00:00:00.0001905}実行中に完了する
var versions = methodInfo.DeclaringType.GetConstructors().SelectMany(x =>
x.DeclaringType.CustomAttributes.Where(y =>
y.AttributeType == typeof(ApiVersionAttribute))
.SelectMany(z => z.ConstructorArguments.Select(i=>i.Value)));
取った {00:00:00.0000626}
ちょっとした違いについて話しているのはわかっていますが、それでもまだです。
@ArlanGありがとう、ありがとう。 Asp.Net Core 3.1で動作します。私の見解では、1つの明確な説明があります。主な回答のような同様の動作を取得したい場合、DocInclusionPredicate（）の@Alezisメソッドの実装は次のようになります。
options.DocInclusionPredicate((version, desc) =>
{
if (!desc.TryGetMethodInfo(out MethodInfo methodInfo)) return false;
var versions = methodInfo.DeclaringType
.GetCustomAttributes(true)
.OfType<ApiVersionAttribute>()
.SelectMany(attr => attr.Versions);
var maps = methodInfo
.GetCustomAttributes(true)
.OfType<MapToApiVersionAttribute>()
.SelectMany(attr => attr.Versions)
.ToArray();
return versions.Any(v => $"v{v.ToString()}" == version)
&& (!maps.Any() || maps.Any(v => $"v{v.ToString()}" == version));
});
この場合、SwaggerUiページでバージョンを選択すると、このバージョンにマップされているコントローラーメソッドのみが表示されます。