1

我正在为我的项目使用 asp dotnet core 3.1。目前,我正在按照建议的方式对我的1.0操作进行版本控制。2.1但是我想通过例如schooljob或其他一些随机字符串值来对我的操作进行版本控制。我研究了很多,一些网站声称可以这样做1_0,但1.0 没有说明如何做。另外,我不知道是否可以将版本控制更改为schooljob.

对于我的 URL,我真正想做的是将它们从 更改为...someUrl/1.0/getTeachers...someUrl/schooljob/getTeachers以便我最终可以在 Swagger 中更好地对它们进行分组。

// SchoolController.cs
[ApiVersion("1.0")]  //I want to change it as [ApiVersion("schooljob")]
[ApiController]
[Route("{version:apiVersion}")]
public class SchoolController : AbstractController
{
   ...

   [HttpPost("schooljob/getstudents")]
   public JsonResult GetStudents([FromBody]Student student)
   { ... }
}
// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    c.SwaggerDoc("schooljob", new OpenApiInfo
    {
        Version = "schooljob",
        Title = "School Job"
    });
    // c.AddSecurityDefinition... and other swagger configurations
}   
public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IServiceProvider serviceProvider)
{
    app.UseSwagger(c =>
    {
        c.RouteTemplate = "mainproject/swagger/{documentname}/swagger.json";
    });
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/mainproject/swagger/schooljob/swagger.json", "School Job");
        c.RoutePrefix = "mainproject/swagger";
    });
}
4

1 回答 1

0

简短的回答 -- 您不能以这种方式定义 API 版本。它具有无法更改的规定格式。这对于整理、排序和比较很重要。例如,1.0 > 1.0-beta

看起来您想要做的是将您的 API 分组。默认行为是使用格式化的 API 版本文本作为 API 描述的组名。这是连接其他库(如 Swashbuckle 或 NSwag)进行分组的桥梁。有几种方法可以改变这种行为。您可以将其更改为 API Explorer 扩展(la IApiDescriptionProvider)或 OpenAPI/Swagger 文档生成器扩展。要获得您想要的结果,您只需对结果进行重新排序/分组。

大多数分组是按 API 版本完成的,但当然也可以按资源或类别进行分组。由于 API 版本控制会覆盖默认组名,因此您需要重新提取源属性中定义的原始组名或使用自定义属性。您可能能够从模板约定或其他元数据构建它。

例子

首先,您需要一种方法来按照您想要的方式比较 2 个ApiDescription实例:

public class MyComparer : IComparer<ApiDescription>
{
    public int Compare(ApiDescription x, ApiDescription y)
    {
        if (x == null)
        {
            return y == null ? 0 : -1;
        }

        if (y == null)
        {
            return 1;
        }

        var comparer = StringComparer.OrdinalIgnoreCase;
        var result = comparer.Compare(x.GroupName, y.GroupName);

        // compare by group name, then api version
        return result == 0 ? x.GetApiVersion().CompareTo(y.GetApiVersion()) : result;
    }
}

然后,您可以创建一个自定义IApiDescriptionProvider来处理发现的描述:

public class MyApiDescriptionProvider : IApiDescriptionProvider
{
    // important: you may need to increase the value to run later in the sequence
    public int Order => 0;

    public void OnProvidersExecuting(ApiDescriptionProviderContext context) { }

    public void OnProvidersExecuted(ApiDescriptionProviderContext context)
    {
        var sorted = context.Results.ToList();

        sorted.Sort(new MyComparer());
        context.Results.Clear();

        for (var i = 0; i < sorted.Count; i++)
        {
            context.Results.Add(sorted[i]);
        }
    }
}

最后,在您的设置中注册您的提供商:

services.TryAddEnumerable(
  ServiceDescriptor.Transient<IApiDescriptionProvider, MyApiDescriptionProvider>() );
于 2020-09-16T20:55:37.410 回答