首页 文章

使用操作约束时在MVC 6中使用Swagger的多个Api版本

提问于
浏览 次
6

希望有人尝试过与MVC 6和Swagger中的版本化API类似的东西，以显示有关不同版本的文档 .

我按照this ASP.NET 5 repository在MVC 6中使用推荐的API版本控制 . 我所做的唯一改变是GetVersion方法从请求的自定义http头读取api版本：

//in VersionRangeValidator.cs
public static string GetVersion(HttpRequest request)
{
        //return request.Query["version"];
        if (!string.IsNullOrWhiteSpace(request.Headers[Constants.CommonRoutingDefinitions.ApiVersionSegmentName]))
        {
            return request.Headers[Constants.CommonRoutingDefinitions.ApiVersionSegmentName];
        }
        return Constants.CommonRoutingDefinitions.CurrentApiVersion;
 }

我有一个像这样的控制器：

[Route("api/[controller]")]
[Produces(Constants.MediaTypeNames.ApplicationJson)]
public class TagsController : Controller
{
    private readonly ITagService _tagService;

    public TagsController(ITagService tagService)
    {
        _tagService = tagService;
    }

    /// <summary>
    /// Version 1 by default
    /// </summary>
    /// <returns>All the tags</returns>
    [HttpGet]
    [Produces(typeof(IEnumerable<Tag>))]
    public IEnumerable<Tag> GetTags()
    {
        IEnumerable<Tag> tags = _tagService.GetTags();
        return tags;
    }

    /// <summary>
    /// Version 2
    /// </summary>
    /// <returns>All the tags V2</returns>
    [VersionGet("", versionRange: "[2]")]
    public IEnumerable<Tag> GetTagsV2()
    {
        IList<Tag> tags = new List<Tag>
        {
            new Tag { Id = 1, Links = Enumerable.Empty<Link>().ToList(), Name = "Tag version 2" }
        };
        return tags;
    }
}

使用自定义http标头进行版本控制即可

GET / api / tags Content-Type：application / json

默认情况下将触发GetTags（）操作，因为没有指定标头和

GET / api / tags api-version：2 Content-Type：application / json

将点击GetTagsV2（）动作 .

我已经按照this blog的步骤添加了Swagger UI和Swagger GEN库，所以在我的 project.json 中我有以下依赖项：

"Swashbuckle.SwaggerGen": "6.0.0-rc1-final",
"Swashbuckle.SwaggerUi": "6.0.0-rc1-final"

然后在我的Startup.cs中，我将Swagger添加到管道中

//inside Configure(IApplicationBuilder app)
 app.UseSwaggerGen();
 app.UseSwaggerUi();

我按如下方式配置Swagger：

private void ConfigureSwagger(IServiceCollection services)
{
        services.AddSwaggerGen();

        services.ConfigureSwaggerDocument(options =>
        {
            options.MultipleApiVersions(new Swashbuckle.SwaggerGen.Info[]
            {
                new Swashbuckle.SwaggerGen.Info
                {
                    Version = "v1",
                    Title = "MyApp API",
                    Description = "A RESTful API"
                },
                new Swashbuckle.SwaggerGen.Info
                {
                    Version = "v2",
                    Title = "MyApp API (v2)",
                    Description = "A RESTful API"
                }
            }, (description, version) => {
                //description is an instance of ApiDescription and 
                //version is either "v1" or "v2" 
                //depending on the user choice in swagger UI page
                //TODO, how can I know whether the action belongs to v1 or to v2 to return true or false as appropriate?
            });
            options.OperationFilter(new Swashbuckle.SwaggerGen.XmlComments.ApplyXmlActionComments(Configuration["Documentation:SwaggerDocXml"]));
        });

        services.ConfigureSwaggerSchema(options =>
        {
            options.DescribeAllEnumsAsStrings = true;
            options.ModelFilter(new Swashbuckle.SwaggerGen.XmlComments.ApplyXmlTypeComments(Configuration["Documentation:SwaggerDocXml"]));
        });
}

问题是 I don't know how to get from the description （这是Microsoft.AspNet.Mvc.ApiExplorer.ApiDescription的一个实例） the necessary information to know whether that given action has to be displayed in Swagger UI or not depending on the specified version . 任何提示将不胜感激 . 这将有助于理解版本控制的this ASP.NET 5 repository实现是如何工作的，因为我仍然不能很好地理解它，并且无法找到关于动作约束如何工作的良好解释 .

PS：This stackoverflow question帮我实现了MVC 6的版本控制，但是我找不到很多关于Swagger如何与这种版本化API的方式集成 .

asp.net-core swagger asp.net-core-mvc swagger-ui api-versioning

2 回答

  • 2

    我在这里回答第一个问题，希望你发现它很有用 . 我为代码片段的格式错误道歉，但现在我手上的时间很少 .

    你几乎就在那里，但你没有在描述中添加版本的过滤器 . 这适用于我的以下url格式的实现：

    "/v1/Sessions" and "/v3/Sessions"


options.MultipleApiVersions(new Info[]{
new Info
{
        Version = "v1",
        Title = "your_own",
        Description = "Defines the API to access... your_own",
        TermsOfService = "your_own",
        Contact = new Contact()
        {
            Email = "your_own",
            Name = "your_own"
        }
},
new Info
    {
        Version = "v3",
        Title = "your_own",
        Description =
            "Defines the API to .... your_own",
        TermsOfService = "your_own",
        Contact = new Contact()
        {
            Email = "your_own",
            Name = "your_own"
        }
    }}, (description, version) => {
//Here we compare if the version is part of the incoming URI, if yes, show it on swagger page.
return description.RelativePath.ToLower().Contains(version.ToLower()); } );
    回复于
  • 2

    您似乎拥有自定义 VersionGet 属性 . 您可以使用它来确定v2 endpoints . 其他 endpoints 可能默认为v1（如果这是您想要的） .

    这是我使用的片段 . 请注意，我的自定义属性名为 ApiVersion2 .

    public static bool ResolveVersion(ApiDescription apiDesc, string targetApiVersion)
{
    if (targetApiVersion == "v2")
    {
        ApiVersion2Attribute v2Attr = apiDesc.ActionDescriptor.GetCustomAttributes<ApiVersion2Attribute>().FirstOrDefault();
        if (v2Attr != null)
            return true;
    }

    if (targetApiVersion == "v1")
        return true;

    throw new NotSupportedException();
}
    回复于

相关问题