NSwag 和 ASP.NET Core 入门

NSwag 提供了下列功能：

能够使用 Swagger UI 和 Swagger 生成器。
灵活的代码生成功能。
借助 NSwag，无需使用现有 API。也就是说，可使用包含 Swagger 的第三方 API，并生成客户端实现。 使用 NSwag，可以加快开发周期，并轻松适应 API 更改。

包安装
将 NSwag 安装到：

生成已实现的 Web API 的 Swagger 规范。
为 Swagger UI 提供服务以浏览和测试 Web API。
为 Redoc 提供服务，以为 Web API 添加 API 文档。
若要使用 NSwag ASP.NET Core 中间件，请安装 NSwag.AspNetCore NuGet 包。 此包内的中间件可用于生成并提供Swagger 规范、Swagger UI（v2 和 v3）和 ReDoc UI。 NSwag 14 仅支持 v3 版的 Swagger UI 规范。

若要安装 NSwag NuGet 包，请使用以下方法之一：

Visual Studio
Visual Studio for Mac
Visual Studio Code
.NET CLI
从“程序包管理器控制台”窗口：

转到“视图”>“其他窗口”>“程序包管理器控制台”

导航到包含 NSwagSample.csproj 文件的目录

请执行以下命令：

PowerShell

复制
Install-Package NSwag.AspNetCore
从“管理 NuGet 程序包”对话框中：

右键单击“解决方案资源管理器”>“管理 NuGet 包”中的项目
将“包源”设置为“nuget.org”
在搜索框中输入“NSwag.AspNetCore”
从“浏览”选项卡中选择“NSwag.AspNetCore”包，然后单击“安装”
添加并配置 Swagger 中间件
通过执行以下步骤，在 ASP.NET Core 应用中添加和配置 Swagger：

将 OpenApi 生成器添加到 Program.cs 中的服务集合：
C#

复制
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApiDocument();
启用中间件来提供生成的 OpenApi 规范、Swagger UI 和 Redoc UI，同时在 Program.cs 中：
C#

复制
if (app.Environment.IsDevelopment())
{
// Add OpenAPI 3.0 document serving middleware
// Available at: http://localhost:/swagger/v1/swagger.json
app.UseOpenApi();

// Add web UIs to interact with the document
// Available at: http://localhost:/swagger
app.UseSwaggerUi(); // UseSwaggerUI Protected by if (env.IsDevelopment())

}
启动应用。 转到：
http://localhost:/swagger，以查看 Swagger UI。
http://localhost:/swagger/v1/swagger.json，以查看 Swagger 规范。
代码生成
若要利用 NSwag 的代码生成功能，可选择以下选项之一：

NSwagStudio：一款 Windows 桌面应用，用于在 C# 或 TypeScript 中生成 API 客户端代码。
NSwag.CodeGeneration.CSharp 或 NSwag.CodeGeneration.TypeScript NuGet 包 - 用于在项目中生成代码。
通过命令行使用 NSwag。
NSwag.MSBuild NuGet 包。
Unchase OpenAPI (Swagger) Connected Service（Unchase OpenAPI (Swagger) 连接服务）：一种 Visual Studio 连接服务，用于在 C# 或 TypeScript 中生成 API 客户端代码。 还可以使用 NSwag 为 OpenAPI 服务生成 C# 控制器。
使用 NSwagStudio 生成代码
按照 NSwagStudio GitHub 存储库中的说明操作，以安装 NSwagStudio。 在 NSwag 发布页面上，可以下载无需安装和管理员权限即可启动的 xcopy 版本。
启动 NSwagStudio，并在“Swagger 规范 URL”文本框中输入 swagger.json 文件 URL。 例如 http://localhost:5232/swagger/v1/swagger.json。
单击“创建本地副本”按钮，以生成 Swagger 规范的 JSON 表示形式。
NSwag Studio 导入规范并导出 CSharp 客户端。

在“输出”区域中，单击“CSharp 客户端”复选框。 也可以选中“TypeScript 客户端”或“C# Web API 控制器”，具体视项目而定。 如果选中“C# Web API 控制器”，服务规范会重新生成服务，起到反向生成的作用。
单击“生成输出”，以生成 TodoApi.NSwag 项目的完整 C# 客户端实现。 若要查看生成的客户端代码，请单击“C# 客户端”选项卡：
C#

复制
namespace MyNamespace
{
using System = global::System;

[System.CodeDom.Compiler.GeneratedCode("NSwag", "14.0.1.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))")]
public partial class TodoClient
{
#pragma warning disable 8618 // Set by constructor via BaseUrl property
    private string _baseUrl;
#pragma warning restore 8618 // Set by constructor via BaseUrl property
    private System.Net.Http.HttpClient _httpClient;
    private static System.Lazy _settings = new System.Lazy(CreateSerializerSettings, true);

    public TodoClient(System.Net.Http.HttpClient httpClient)
    {
        BaseUrl = "http://localhost:5232";
        _httpClient = httpClient;
    }

    private static Newtonsoft.Json.JsonSerializerSettings CreateSerializerSettings()
    {
        var settings = new Newtonsoft.Json.JsonSerializerSettings();
        UpdateJsonSerializerSettings(settings);
        return settings;
    }

    public string BaseUrl
    {
        get { return _baseUrl; }
        set
        {
            _baseUrl = value;
            if (!string.IsNullOrEmpty(_baseUrl) && !_baseUrl.EndsWith("/"))
                _baseUrl += '/';
        }
    }
    // code omitted for brevity

提示

C# 客户端代码的生成依据是，“设置”选项卡中的选择。修改设置以执行任务，例如默认命名空间重命名和同步方法生成。

将生成的 C# 代码复制到使用 API 的客户端项目内的文件中。
开始使用 Web API：
C#

复制
var todoClient = new TodoClient(new HttpClient());

// Gets all to-dos from the API
var allTodos = await todoClient.GetAsync();

// Create a new TodoItem, and save it via the API.
await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);