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

刺骨的言语ヽ痛彻心扉 2023-05-28 12:52 23阅读 0赞

官网介绍

使用 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][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` 方法中的服务集合中：

在 `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` 方法调用启用了[静态文件中间件][Link 1]。 如果以 .NET Framework 或 .NET Core 1.x 为目标，请将 [Microsoft.AspNetCore.StaticFiles][] NuGet 包添加到项目。

启动应用，并导航到 `http://localhost:<port>/swagger/v1/swagger.json`。 生成的描述终结点的文档显示在 [Swagger 规范 (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;
    using System.Reflection;
    using System.IO;

### API 信息和说明 ###

传递给 `AddSwaggerGen` 方法的配置操作会添加诸如作者、许可证和说明的信息：

C\#复制

// Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = new Uri("https://twitter.com/spboyer"),
            },
            License = new OpenApiLicense
            {
                Name = "Use under LICX",
                Url = new Uri("https://example.com/license"),
            }
        });
    });

Swagger UI 显示版本的信息：

![包含版本信息的 Swagger UI：说明、作者以及查看更多链接][Swagger UI]

### XML 注释 ###

可使用以下方法启用 XML 注释：

*  [Visual Studio][]
 *  [Visual Studio for Mac][]
 *  [Visual Studio Code][]
 *  [.NET Core CLI][]

*  在 Solution Pad 中，按 control 并单击项目名称 。 导航到“工具” > “编辑文件” 。
 *  手动将突出显示的行添加到 .csproj 文件 ：

XML复制

<PropertyGroup>
      <GenerateDocumentationFile>true</GenerateDocumentationFile>
      <NoWarn>$(NoWarn);1591</NoWarn>
    </PropertyGroup>

启用 XML 注释，为未记录的公共类型和成员提供调试信息。 警告消息指示未记录的类型和成员。 例如，以下消息指示违反警告代码 1591：

text复制

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

要在项目范围内取消警告，请定义要在项目文件中忽略的以分号分隔的警告代码列表。 将警告代码追加到 `$(NoWarn);` 也会应用 [C\# 默认值][C_]。

XML复制

<PropertyGroup>
      <GenerateDocumentationFile>true</GenerateDocumentationFile>
      <NoWarn>$(NoWarn);1591</NoWarn>
    </PropertyGroup>

要仅针对特定成员取消警告，请将代码附入 [\#pragma warning][pragma warning] 预处理程序指令中。 此方法对于不应通过 API 文档公开的代码非常有用。在以下示例中，将忽略整个 `Program` 类的警告代码 CS1591。 在类定义结束时还原警告代码的强制执行。 使用逗号分隔的列表指定多个警告代码。

C\#复制

namespace TodoApi
    {
    #pragma warning disable CS1591
        public class Program
        {
            public static void Main(string[] args) =>
                BuildWebHost(args).Run();
    
            public static IWebHost BuildWebHost(string[] args) =>
                WebHost.CreateDefaultBuilder(args)
                    .UseStartup<Startup>()
                    .Build();
        }
    #pragma warning restore CS1591
    }

将 Swagger 配置为使用按照上述说明生成的 XML 文件。 对于 Linux 或非 Windows 操作系统，文件名和路径区分大小写。 例如，“TodoApi.XML”文件在 Windows 上有效，但在 CentOS 上无效 。

C\#复制

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
            {
                Version = "v1",
                Title = "ToDo API",
                Description = "A simple example ASP.NET Core Web API",
                TermsOfService = new Uri("https://example.com/terms"),
                Contact = new OpenApiContact
                {
                    Name = "Shayne Boyer",
                    Email = string.Empty,
                    Url = new Uri("https://twitter.com/spboyer"),
                },
                License = new OpenApiLicense
                {
                    Name = "Use under LICX",
                    Url = new Uri("https://example.com/license"),
                }
            });
    
            // Set the comments path for the Swagger JSON and UI.
            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
            c.IncludeXmlComments(xmlPath);
        });
    }

在上述代码中，[反射][Link 2]用于生成与 Web API 项目相匹配的 XML 文件名。 [AppContext.BaseDirectory][]属性用于构造 XML 文件的路径。 一些 Swagger 功能（例如，输入参数的架构，或各自属性中的 HTTP 方法和响应代码）无需使用 XML 文档文件即可起作用。 对于大多数功能（即方法摘要以及参数说明和响应代码说明），必须使用 XML 文件。

通过向节标题添加说明，将三斜杠注释添加到操作增强了 Swagger UI。 执行 `Delete` 操作前添加 [<summary>][summary] 元素：

C\#复制

/// <summary>
    /// Deletes a specific TodoItem.
    /// </summary>
    /// <param name="id"></param>        
    [HttpDelete("{id}")]
    public IActionResult Delete(long id)
    {
        var todo = _context.TodoItems.Find(id);
    
        if (todo == null)
        {
            return NotFound();
        }
    
        _context.TodoItems.Remove(todo);
        _context.SaveChanges();
    
        return NoContent();
    }

Swagger UI 显示上述代码的 `<summary>` 元素的内部文本：

![显示 DELETE 方法的 XML 注释“删除特定 TodoItem”][DELETE _ XML _ TodoItem]

生成的 JSON 架构驱动 UI：

JSON复制

"delete": {
        "tags": [
            "Todo"
        ],
        "summary": "Deletes a specific TodoItem.",
        "operationId": "ApiTodoByIdDelete",
        "consumes": [],
        "produces": [],
        "parameters": [
            {
                "name": "id",
                "in": "path",
                "description": "",
                "required": true,
                "type": "integer",
                "format": "int64"
            }
        ],
        "responses": {
            "200": {
                "description": "Success"
            }
        }
    }

将 [<remarks>][remarks] 元素添加到 `Create` 操作方法文档。 它可以补充 `<summary>` 元素中指定的信息，并提供更可靠的 Swagger UI。 `<remarks>` 元素内容可包含文本、JSON 或 XML。

C\#复制

/// <summary>
    /// Creates a TodoItem.
    /// </summary>
    /// <remarks>
    /// Sample request:
    ///
    ///     POST /Todo
    ///     {
    ///        "id": 1,
    ///        "name": "Item1",
    ///        "isComplete": true
    ///     }
    ///
    /// </remarks>
    /// <param name="item"></param>
    /// <returns>A newly created TodoItem</returns>
    /// <response code="201">Returns the newly created item</response>
    /// <response code="400">If the item is null</response>            
    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public ActionResult<TodoItem> Create(TodoItem item)
    {
        _context.TodoItems.Add(item);
        _context.SaveChanges();
    
        return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
    }

请注意带这些附加注释的 UI 增强功能：

![显示包含其他注释的 Swagger UI][Swagger UI 1]

### 数据注释 ###

使用 [System.ComponentModel.DataAnnotations][] 命名空间中的属性来标记模型，以帮助驱动 Swagger UI 组件。

将 `[Required]` 属性添加到 `TodoItem` 类的 `Name` 属性：

C\#复制

using System.ComponentModel;
    using System.ComponentModel.DataAnnotations;
    
    namespace TodoApi.Models
    {
        public class TodoItem
        {
            public long Id { get; set; }
    
            [Required]
            public string Name { get; set; }
    
            [DefaultValue(false)]
            public bool IsComplete { get; set; }
        }
    }

此属性的状态更改 UI 行为并更改基础 JSON 架构：

JSON复制

"definitions": {
        "TodoItem": {
            "required": [
                "name"
            ],
            "type": "object",
            "properties": {
                "id": {
                    "format": "int64",
                    "type": "integer"
                },
                "name": {
                    "type": "string"
                },
                "isComplete": {
                    "default": false,
                    "type": "boolean"
                }
            }
        }
    },

将 `[Produces("application/json")]` 属性添加到 API 控制器。 这样做的目的是声明控制器的操作支持 application/json 的响应内容类型 ：

C\#复制

[Produces("application/json")]
    [Route("api/[controller]")]
    [ApiController]
    public class TodoController : ControllerBase
    {
        private readonly TodoContext _context;

“响应内容类型” 下拉列表选此内容类型作为控制器的默认 GET 操作：

![包含默认响应内容类型的 Swagger UI][Swagger UI 2]

随着 Web API 中的数据注释的使用越来越多，UI 和 API 帮助页变得更具说明性和更为有用。

### 描述响应类型 ###

使用 Web API 的开发人员最关心的问题是返回的内容，特别是响应类型和错误代码（如果不标准）。 在 XML 注释和数据注释中表示响应类型和错误代码。

`Create` 操作成功后返回 HTTP 201 状态代码。 发布的请求正文为 NULL 时，将返回 HTTP 400 状态代码。 如果 Swagger UI 中没有提供合适的文档，那么使用者会缺少对这些预期结果的了解。 在以下示例中，通过添加突出显示的行解决此问题：

C\#复制

Swagger UI 现在清楚地记录预期的 HTTP 响应代码：

![Swagger UI 针对“响应消息”下的状态代码和原因显示 POST 响应类描述“返回新建的待办事项”和“400 - 如果该项为 null”][Swagger UI _ POST _400 - _ null]

在 ASP.NET Core 2.2 或更高版本中，约定可以用作使用 `[ProducesResponseType]` 显式修饰各操作的替代方法。 有关详细信息，请参阅 [使用 Web API 约定][Web API]。

### 自定义 UI ###

股票 UI 既实用又可呈现。 但是，API 文档页应代表品牌或主题。 将 Swashbuckle 组件标记为需要添加资源以提供静态文件，并构建文件夹结构以托管这些文件。

如果以 .NET Framework 或 .NET Core 1.x 为目标，请将 [Microsoft.AspNetCore.StaticFiles][Microsoft.AspNetCore.StaticFiles 1] NuGet 包添加到项目：

XML复制

如果以 .NET Core 2.x 为目标并使用[元包][Link 3]，则已安装上述 NuGet 包。

启用静态文件中间件：

C\#复制

public void Configure(IApplicationBuilder app)
    {
        app.UseStaticFiles();
    
        // 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();
        });
    }

从 [Swagger UI GitHub 存储库][Swagger UI GitHub]中获取 dist 文件夹的内容。 此文件夹包含 Swagger UI 页必需的资产。

创建 wwwroot/swagger/ui 文件夹，然后将 dist 文件夹的内容复制到其中 。

使用以下 CSS 在 wwwroot/swagger/ui 中创建 custom.css 文件，以自定义页面标题 ：

css复制

.swagger-ui .topbar {
        background-color: #000;
        border-bottom: 3px solid #547f00;
    }

引用其他 CSS 文件后，引用“ui”文件夹内 index.html 文件中的 custom.css ：

HTML复制

浏览到 `http://localhost:<port>/swagger/ui/index.html` 中的 index.html 页。 在标题文本框中输入 `https://localhost:<port>/swagger/v1/swagger.json`，然后单击“浏览” 按钮。 生成的页面如下所示：

![使用自定义标题的 Swagger UI][Swagger UI 3]

还可以对页面执行更多操作。 在 [Swagger UI GitHub 存储库][Swagger UI GitHub 1]中查看 UI 资源的完整功能。

[Swagger]: https://swagger.io/
[OpenAPI]: https://www.openapis.org/
[https_docs.microsoft.com_zh-cn_aspnet_core_tutorials_web-api-help-pages-using-swagger_view_aspnetcore-3.1]: https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-3.1
[Link 1]: https://docs.microsoft.com/zh-cn/aspnet/core/fundamentals/static-files?view=aspnetcore-3.1
[Microsoft.AspNetCore.StaticFiles]: https://www.nuget.org/packages/Microsoft.AspNetCore.StaticFiles/
[Swagger _ _swagger.json]: https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-3.1#swagger-specification-swaggerjson
[Swagger UI]: /images/20230528/7b88664d260d4083b92e840adf24d8fc.png
[Visual Studio]: https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio-mac#tabpanel_CeZOj-G++Q-1_visual-studio
[Visual Studio for Mac]: https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio-mac#tabpanel_CeZOj-G++Q-1_visual-studio-mac
[Visual Studio Code]: https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio-mac#tabpanel_CeZOj-G++Q-1_visual-studio-code
[.NET Core CLI]: https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio-mac#tabpanel_CeZOj-G++Q-1_netcore-cli
[C_]: https://github.com/dotnet/sdk/blob/2eb6c546931b5bcb92cd3128b93932a980553ea1/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.Sdk.CSharp.props#L16
[pragma warning]: https://docs.microsoft.com/zh-cn/dotnet/csharp/language-reference/preprocessor-directives/preprocessor-pragma-warning
[Link 2]: https://docs.microsoft.com/zh-cn/dotnet/csharp/programming-guide/concepts/reflection
[AppContext.BaseDirectory]: https://docs.microsoft.com/zh-cn/dotnet/api/system.appcontext.basedirectory
[summary]: https://docs.microsoft.com/zh-cn/dotnet/csharp/programming-guide/xmldoc/summary
[DELETE _ XML _ TodoItem]: /images/20230528/87cb37713a3a4f3d84d0db62dd03bb28.png
[remarks]: https://docs.microsoft.com/zh-cn/dotnet/csharp/programming-guide/xmldoc/remarks
[Swagger UI 1]: /images/20230528/042080612f934114a31030a87ff1ba4a.png
[System.ComponentModel.DataAnnotations]: https://docs.microsoft.com/zh-cn/dotnet/api/system.componentmodel.dataannotations
[Swagger UI 2]: /images/20230528/4669996234464ec98b90f8e436c38ea6.png
[Swagger UI _ POST _400 - _ null]: /images/20230528/d283e1b81c7e4a0d86f5246a59b9d201.png
[Web API]: https://docs.microsoft.com/zh-cn/aspnet/core/web-api/advanced/conventions?view=aspnetcore-3.1
[Microsoft.AspNetCore.StaticFiles 1]: https://www.nuget.org/packages/Microsoft.AspNetCore.StaticFiles
[Link 3]: https://docs.microsoft.com/zh-cn/aspnet/core/fundamentals/metapackage?view=aspnetcore-3.1
[Swagger UI GitHub]: https://github.com/swagger-api/swagger-ui/tree/master/dist
[Swagger UI 3]: /images/20230528/af85486a055f4077a0269f1805a4700b.png
[Swagger UI GitHub 1]: https://github.com/swagger-api/swagger-ui