给asp.net core API增加目录浏览Swagger/OpenAPI

官网介绍

使用 Web API 时，了解其各种方法对开发人员来说可能是一项挑战。 Swagger 也称为OpenAPI，解决了为 Web API 生成有用文档和帮助页的问题。 它具有诸如交互式文档、客户端 SDK 生成和 API 可发现性等优点。

https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-3.1

 

• 右键单击项目 > “添加NuGet包...” 
• 选择浏览
• 确保启用“显示预发行包”选项
• 在搜索框中输入“Swashbuckle.AspNetCore”
• 从结果窗格中选择最新的“Swashbuckle.AspNetCore”包，然后单击“添加包”

添加并配置 Swagger 中间件

在 Startup 类中，导入以下命名空间来使用 OpenApiInfo 类：

using Microsoft.OpenApi.Models;

将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中：

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
}

在 Startup.Configure 方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务：

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

前面的 UseSwaggerUI 方法调用启用了静态文件中间件。 如果以 .NET Framework 或 .NET Core 1.x 为目标，请将 Microsoft.AspNetCore.StaticFiles NuGet 包添加到项目。

启动应用，并导航到 http://localhost:<port>/swagger/v1/swagger.json。 生成的描述终结点的文档显示在 Swagger 规范 (swagger.json) 中。

可在 http://localhost:<port>/swagger 找到 Swagger UI。 通过 Swagger UI 浏览 API，并将其合并其他计划中。

 提示

要在应用的根 (http://localhost:<port>/) 处提供 Swagger UI，请将 RoutePrefix 属性设置为空字符串：

C#复制

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});

如果使用目录及 IIS 或反向代理，请使用 ./ 前缀将 Swagger 终结点设置为相对路径。 例如 ./swagger/v1/swagger.json。 使用 /swagger/v1/swagger.json 指示应用在 URL 的真实根目录中查找 JSON 文件（如果使用，加上路由前缀）。 例如，请使用 http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json 而不是 http://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json。

自定义和扩展

Swagger 提供了为对象模型进行归档和自定义 UI 以匹配你的主题的选项。

在 Startup 类中，添加以下命名空间：

C#复制

using System;
usin