.NET Core 的 Swagger 接口文档使用教程

落日映苍穹つ 2023-09-27 16:34 83阅读 0赞

![ac08231da01d23314d811f790899535f.png][]

.NET Core 是一个跨平台的开发框架，它可以用于构建各种类型的应用程序，包括 Web API。Web API 是一种基于 HTTP 的服务，它可以提供数据和功能给客户端应用程序，如浏览器、移动设备或其他服务器。为了让客户端应用程序更容易地理解和使用 Web API，我们需要提供一种描述 Web API 的文档，这就是 Swagger（或 OpenAPI）的作用。

Swagger（或 OpenAPI）是一种用于描述 REST API 的语言无关规范。它可以让计算机和人类在不直接访问源代码的情况下，理解 REST API 的功能和参数。它的主要目标是：

*  减少连接解耦服务所需的工作量。

*  减少准确记录服务所需的时间。

Swagger 规范是一个 JSON 格式的文档，它定义了 API 的基本信息、路径、操作、参数、响应和模式等内容。Swagger UI 是一个基于 Web 的工具，它可以根据 Swagger 规范生成一个可视化和交互式的界面，让用户可以浏览和测试 API。

在 .NET Core 中，有两个主要的 OpenAPI 实现，分别是 Swashbuckle 和 NSwag。在本教程中，我们将使用 Swashbuckle 来生成和展示 Swagger 文档。

首先，我们需要创建一个 .NET Core Web API 项目，并安装 Swashbuckle.AspNetCore 包。我们可以使用 Visual Studio、Visual Studio Code 或 .NET Core CLI 来完成这些步骤。安装好 Swashbuckle.AspNetCore 包后，我们需要在 Program.cs 中添加和配置 Swagger 生成器和中间件。Swagger 生成器可以从路由、控制器和模型直接生成 SwaggerDocument 对象，并公开为 JSON 终结点。Swagger 中间件可以为生成的 JSON 文档和 Swagger UI 提供服务。

在 Program.cs 中，我们需要添加以下代码：

using Microsoft.OpenApi.Models; // 导入命名空间
    
    builder.Services.AddControllers(); // 添加控制器服务
    builder.Services.AddEndpointsApiExplorer(); // 添加终结点 API 浏览器服务
    builder.Services.AddSwaggerGen(options => // 添加 Swagger 生成器服务
    {
        options.SwaggerDoc("v1", new OpenApiInfo // 配置 Swagger 文档信息
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "An ASP.NET Core Web API for managing ToDo items",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Example Contact",
                Url = new Uri("https://example.com/contact")
            },
            License = new OpenApiLicense
            {
                Name = "Example License",
                Url = new Uri("https://example.com/license")
            }
        });
    });
    
    var app = builder.Build();
    
    if (app.Environment.IsDevelopment()) // 判断是否为开发环境
    {
        app.UseSwagger(); // 启用 Swagger 中间件
        app.UseSwaggerUI(options => // 启用 Swagger UI 中间件
        {
            options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1"); // 配置 Swagger 终结点
            options.RoutePrefix = string.Empty; // 设置路由前缀为空字符串
        });
    }
    
    app.UseHttpsRedirection();
    
    app.UseAuthorization();
    
    app.MapControllers();
    
    app.Run();

启动应用后，我们可以在 [https://localhost][https_localhost]:<port>/swagger/v1/swagger.json 看到生成的 Swagger 规范文档，如下所示：

{
      "openapi": "3.0.1",
      "info": {
        "title": "ToDo API",
        "version": "v1",
        "description": "An ASP.NET Core Web API for managing ToDo items",
        "termsOfService": "https://example.com/terms",
        "contact": {
          "name": "Example Contact",
          "url": "https://example.com/contact"
        },
        "license": {
          "name": "Example License",
          "url": "https://example.com/license"
        }
      },
      "paths": {
        "/api/Todo": {
          "get": {
            "tags": [
              "Todo"
            ],
            "operationId": "ApiTodoGet",
            "responses": {
              "200": {
                "description": "Success",
                "content": {
                  "text/plain": {
                    "schema": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ToDoItem"
                      }
                    }
                  },
                  "application/json": {
                    "schema": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ToDoItem"
                      }
                    }
                  },
                  "text/json": {
                    "schema": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ToDoItem"
                      }
                    }
                  }
                }
              }
            }
          },
          // 省略其他操作
        },
        "/api/Todo/{id}": {
          // 省略其他操作
        }
      },
      // 省略其他内容
    }

Swagger UI 提供了一个可视化和交互式的方式来浏览和测试 API。我们可以选择方法名称来展开区段，添加任何必要的参数，然后选择“试用！”按钮。Swagger UI 会显示请求的 URL、响应状态码、响应头和响应正文等信息。

通过 Swagger UI，我们可以更方便地了解和使用 Web API，也可以更容易地与其他客户端应用程序或服务集成。

除了生成和展示 Swagger 文档，我们还可以自定义和扩展 Swagger 的功能，例如：

*  添加 XML 注释来提供更多的说明和注释。

*  应用过滤器和操作来修改或增强 SwaggerDocument 对象。

*  使用 Swashbuckle.AspNetCore.Annotations 包来启用和丰富响应、架构和参数元数据。

*  使用 Swashbuckle.AspNetCore.ReDoc 包来提供另一种基于 Web 的文档工具 ReDoc。

*  使用 Swashbuckle.AspNetCore.Cli 包来生成静态 Swagger 文件。

[ac08231da01d23314d811f790899535f.png]: https://img-blog.csdnimg.cn/img_convert/ac08231da01d23314d811f790899535f.png
[https_localhost]: https://localhost