# MyOpenApiSwag

**Repository Path**: Peter_Mond/my-open-api-swag

## Basic Information

- **Project Name**: MyOpenApiSwag
- **Description**: 介绍如何使用Swashbuckle、NSwag、Scalar等包提供的Swagger工具为 ASP.NET Core Web API 生成 OpenAPI 文档和交互式帮助页面
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MyOpenApiSwag

一个学习/演示项目，对比 **三种 OpenAPI UI 工具** — Swashbuckle、NSwag 和 Scalar，所有项目均基于 .NET 10 内置的 OpenAPI 文档生成。

## 概述

本解决方案包含三个 Web API 项目，提供相同的 `WeatherForecast` API（一个 `GET /weatherforecast` 端点），唯一区别在于 **渲染交互式 API 文档界面的库不同**。OpenAPI JSON 文档（`/openapi/v1.json`）均由 .NET 内置的 `Microsoft.AspNetCore.OpenApi` 生成。

| 对比项 | SwashbuckleWebApp | NSwagWebApp | ScalarWebApp |
|---|---|---|---|
| **UI 库** | Swashbuckle.AspNetCore 10.2.2 | NSwag.AspNetCore 14.7.1 | Scalar.AspNetCore 2.16.4 |
| **文档生成** | .NET 内置 `AddOpenApi()` | .NET 内置 `AddOpenApi()` | .NET 内置 `AddOpenApi()` |
| **UI 中间件** | `UseSwaggerUI()` | `UseSwaggerUi()` | `MapScalarApiReference()` |
| **OpenAPI 端点** | `/openapi/v1.json` | `/openapi/v1.json` | `/openapi/v1.json` |
| **UI 路径** | `/swagger` | `/swagger` | `/scalar` |
| **HTTP 端口** | 5293 | 5027 | 5115 |
| **HTTPS 端口** | 7125 | 7041 | 7001 |
| **启动时自动打开浏览器** | 否 | 是 | 是 |

## 项目结构

```
MyOpenApiSwag.slnx
└── src/
    ├── SwashbuckleWebApp/
    │   ├── SwashbuckleWebApp.csproj
    │   ├── Program.cs
    │   ├── WeatherForecast.cs
    │   ├── Controllers/
    │   │   └── WeatherForecastController.cs
    │   └── Properties/
    │       └── launchSettings.json
    ├── NSwagWebApp/
    │   ├── NSwagWebApp.csproj
    │   ├── Program.cs
    │   ├── WeatherForecast.cs
    │   ├── Controllers/
    │   │   └── WeatherForecastController.cs
    │   └── Properties/
    │       └── launchSettings.json
    └── ScalarWebApp/
        ├── ScalarWebApp.csproj
        ├── Program.cs
        ├── WeatherForecast.cs
        ├── Controllers/
        │   └── WeatherForecastController.cs
        └── Properties/
            └── launchSettings.json
```

## 运行方式

需要 [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)。

```bash
# 分别在不同终端中启动各项目
dotnet run --project src/SwashbuckleWebApp
dotnet run --project src/NSwagWebApp
dotnet run --project src/ScalarWebApp
```

启动后访问：

- **SwashbuckleWebApp**: `http://localhost:5293/swagger`
- **NSwagWebApp**: `http://localhost:5027/swagger`
- **ScalarWebApp**: `http://localhost:5115/scalar`

## 共同业务逻辑

三个项目的业务代码完全相同，仅命名空间不同。

**WeatherForecast.cs** — 数据模型

```csharp
public class WeatherForecast
{
    public DateOnly Date { get; set; }
    public int TemperatureC { get; set; }
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    public string? Summary { get; set; }
}
```

**WeatherForecastController.cs** — 单个 GET 端点，返回 5 条随机天气数据

```csharp
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries =
    [
        "Freezing", "Bracing", "Chilly", "Cool", "Mild",
        "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    ];

    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        }).ToArray();
    }
}
```

## 各项目 Program.cs 对比

三个项目共同的部分：

```csharp
builder.Services.AddControllers();
builder.Services.AddOpenApi();        // .NET 内置文档生成

app.MapOpenApi();                     // 挂载 /openapi/v1.json 端点
```

差异在于注册的 UI 中间件：

### SwashbuckleWebApp

```csharp
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/openapi/v1.json", "My Open API");
});
```

### NSwagWebApp

```csharp
// builder.Services.AddOpenApiDocument();  // NSwag 也可独立生成文档（绕过内置管道）

app.UseSwaggerUi(options =>
{
    options.DocumentPath = "/openapi/v1.json";
    options.DocumentTitle = "My Open API";
});
```

### ScalarWebApp

```csharp
using Scalar.AspNetCore;  // 需要显式 using

app.MapScalarApiReference();  // 使用路由注册方式，而非中间件
```

## 关键差异说明

**注册方式不同**：Swashbuckle 和 NSwag 使用 `Use*`（中间件），Scalar 使用 `Map*`（路由端点），这是两种不同的 ASP.NET Core 扩展机制。

**NSwag 的可选模式**：`AddOpenApiDocument()` 被注释掉，说明 NSwag 既可以作为独立文档生成器使用，也可以仅作 UI 渲染器消费内置生成的 JSON。

**现代用法的核心思想**：在 .NET 9+ 中，文档生成已内置在框架中（`Microsoft.AspNetCore.OpenApi`）。第三方 UI 库不再负责生成文档，只负责渲染。这三个项目的 OpenAPI JSON 来源完全相同，都是 `/openapi/v1.json`。

## NuGet 包

| 包 | 版本 | 用途 |
|---|---|---|
| `Microsoft.AspNetCore.OpenApi` | 10.0.3 | 生成 OpenAPI v3 JSON（三个项目均使用） |
| `Swashbuckle.AspNetCore` | 10.2.2 | 提供 Swagger UI |
| `NSwag.AspNetCore` | 14.7.1 | 提供 Swagger UI（NSwag 风格）|
| `Scalar.AspNetCore` | 2.16.4 | 提供 Scalar 现代 UI |