每个api版本的swagger xml评论

时间:2015-08-14 13:39:18

标签: asp.net-mvc-4 asp.net-web-api2 swagger-2.0 swashbuckle

我使用ASP.NET Web API 2.1 Custom Route Attributes在visual studio 2015中创建了一个新的asp.net web api 2项目。

我正在使用Swagger(SwashBuckle 5.0)获取API文档,并希望获得每个版本的文档,我设法获得此文档,但是swigger ui显示来自两个版本的相同xml注释。

对于版本1和版本2的api / view的xml注释有些不同的内容在swagger ui上没有出现。

版本1

第2版​​

Version 2

public class SwaggerConfig
{
    public static void Register()
    {
        var thisAssembly = typeof(SwaggerConfig).Assembly;

        GlobalConfiguration.Configuration 
            .EnableSwagger(c =>
                {
                    c.MultipleApiVersions(
                        (apiDesc, targetApiVersion) => ResolveVersionSupportByRouteConstraint(apiDesc, targetApiVersion),
                        (vc) =>
                        {
                            vc.Version("2", "Swagger API V2");
                            vc.Version("1", "Swagger API V1");
                        });

                    c.IncludeXmlComments(GetXmlCommentsPath());
                })
            .EnableSwaggerUi(c => 
            {
                c.EnableDiscoveryUrlSelector();
            });
    }

    private static string GetXmlCommentsPath()
    {
        return String.Format(@"{0}\bin\ChartOfAccounts.Api.XML", AppDomain.CurrentDomain.BaseDirectory);
    }


    private static bool ResolveVersionSupportByRouteConstraint(ApiDescription apiDesc, string targetApiVersion)
    {
        var attr = apiDesc.ActionDescriptor.GetCustomAttributes<VersionedRoute>().FirstOrDefault();

        if (attr == null)
        {
            return true;
        }

        int targetVersion;

        if (int.TryParse(targetApiVersion, out targetVersion))
        {
            return attr.AllowedVersion == targetVersion;
        };

        return true;
    }
}

版本1控制器

[VersionedRoute("api/view", 1)]
public class ViewController : ApiController
{
    private IChartManager _chartManager;

    public ViewController(IChartManager chartManager)
    {
        _chartManager = chartManager;
    }

    /// <summary>
    /// Returns a single view
    /// </summary>
    /// <param name="Id">Used to identify view. {Only Guid Accepted} </param>
    /// <returns></returns>
    public async Task<HttpResponseMessage> GetAsync(Guid Id)
    {
        Chart chart = await _chartManager.GetChartByIdAsync(Id);
        return Request.CreateResponse(HttpStatusCode.OK, chart);
    }
}

版本2 API控制器

[VersionedRoute("api/view", 2)]
public class Viewv2Controller : ApiController
{
    private IChartManager _chartManager;

    public Viewv2Controller(IChartManager chartManager)
    {
        _chartManager = chartManager;
    }

    /// <summary>
    /// Returns a single view of the chart
    /// </summary>
    /// <param name="Id">Used to identify view</param>
    /// <returns></returns>
    public async Task<HttpResponseMessage> GetAsync(string Id)
    {
        Guid newGuidId;
        if (Guid.TryParse(Id, out newGuidId))
        {
            Chart chart = await _chartManager.GetChartByIdAsync(newGuidId);
            return Request.CreateResponse(HttpStatusCode.OK, chart);
        }

        return Request.CreateErrorResponse(HttpStatusCode.NotAcceptable, "Invalid Guid value for Parameter Id.");
    }
}

0 个答案:

没有答案