Swagger/OpenAPI 的 ASP.NET Core Web API 文件

注意

這不是這篇文章的最新版本。 如需目前版本,請參閱 本文的 ASP.NET Core 8.0 版本。

作者:Christoph NienaberRico Suter

Swagger (OpenAPI) 是用來描述 REST API 的語言無關規格。 其可讓電腦和人類了解 REST API 的功能,而不需要直接存取原始程式碼。 其主要目標是:

  • 將連線分離服務所需的工作量降到最低。
  • 減少正確記錄服務所需的時間長短。

.NET 的兩個主要 OpenAPI 實作是 SwashbuckleNSwag,請參閱:

OpenAPI 與Swagger

Swagger 專案於 2015 年已捐贈給 OpenAPI 方案,此後一直將其稱為 OpenAPI。 這兩個名稱會交替使用。 不過,「OpenAPI」是指規格。 「Swagger」是指 SmartBear 中與 OpenAPI 規格搭配使用的開放原始碼和商業產品系列。 後續的開放原始碼產品 (如 OpenAPIGenerator) 儘管不是由 SmartBear 發佈,但也屬於 Swagger 系列名稱。

簡言之:

  • OpenAPI 是規格。
  • Swagger 是使用 OpenAPI 規格的工具。 例如,OpenAPIGenerator 和 SwaggerUI。

OpenAPI 規格 (openapi.json)

OpenAPI 規格是說明 API 功能的文件。 文件是以控制器和模型中的 XML 和屬性註釋為基礎。 其是 OpenAPI 流程的核心部分,可用來驅動 SwaggerUI 之類的工具。 根據預設,會將其命名為 openapi.json。 以下是 OpenAPI 規格的範例,為求簡單明瞭,其已經過縮減:

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "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"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Swagger UI

Swagger UI 使用產生的 OpenAPI 規格提供 Web UI,以提供服務的相關資訊。 Swashbuckle 和 NSwag 都包含內嵌的 Swagger UI 版本,因此它可以使用中介軟體的登錄呼叫裝載在 ASP.NET Core 應用程式中。 Web UI 顯示如下:

Swagger UI

控制器中的每個公用動作方法都可以從 UI 進行測試。 選取方法名稱以展開該區段。 新增任何必要的參數,然後選取 [試試看!]

Example Swagger GET test

注意

用於螢幕擷取畫面的 Swagger UI 版本為第 2 版。 如需第 3 版的範例,請參閱 Petstore 範例

保護 Swagger UI 端點

呼叫 MapSwagger().RequireAuthorization 來保護 Swagger UI 端點。 下列範例會保護 Swagger 端點:

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();

var app = builder.Build();

//if (app.Environment.IsDevelopment())
//{
    app.UseSwagger();
    app.UseSwaggerUI();
//}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapSwagger().RequireAuthorization();

app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
    .RequireAuthorization();

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

在上述程式碼中,/weatherforecast 端點不需要授權,但 Swagger 端點需要。

下列 Curl 會傳遞 JWT 權杖,來測試 Swagger UI 端點:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json

如需使用 JWT 權杖進行測試的詳細資訊,請參閱使用 dotnet user-jwts 產生權杖

在編譯時期產生 XML 檔檔。

如需詳細資訊,請參閱 GenerateDocumentationFile

下一步

作者:Christoph NienaberRico Suter

Swagger (OpenAPI) 是用來描述 REST API 的語言無關規格。 其可讓電腦和人類了解 REST API 的功能,而不需要直接存取原始程式碼。 其主要目標是:

  • 將連線分離服務所需的工作量降到最低。
  • 減少正確記錄服務所需的時間長短。

.NET 的兩個主要 OpenAPI 實作是 SwashbuckleNSwag,請參閱:

OpenAPI 與Swagger

Swagger 專案於 2015 年已捐贈給 OpenAPI 方案,此後一直將其稱為 OpenAPI。 這兩個名稱會交替使用。 不過,「OpenAPI」是指規格。 「Swagger」是指 SmartBear 中與 OpenAPI 規格搭配使用的開放原始碼和商業產品系列。 後續的開放原始碼產品 (如 OpenAPIGenerator) 儘管不是由 SmartBear 發佈,但也屬於 Swagger 系列名稱。

簡言之:

  • OpenAPI 是規格。
  • Swagger 是使用 OpenAPI 規格的工具。 例如,OpenAPIGenerator 和 SwaggerUI。

OpenAPI 規格 (openapi.json)

OpenAPI 規格是說明 API 功能的文件。 文件是以控制器和模型中的 XML 和屬性註釋為基礎。 其是 OpenAPI 流程的核心部分,可用來驅動 SwaggerUI 之類的工具。 根據預設,會將其命名為 openapi.json。 以下是 OpenAPI 規格的範例,為求簡單明瞭,其已經過縮減:

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "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"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Swagger UI

Swagger UI 使用產生的 OpenAPI 規格提供 Web UI,以提供服務的相關資訊。 Swashbuckle 和 NSwag 都包含內嵌的 Swagger UI 版本,因此它可以使用中介軟體的登錄呼叫裝載在 ASP.NET Core 應用程式中。 Web UI 顯示如下:

Swagger UI

控制器中的每個公用動作方法都可以從 UI 進行測試。 選取方法名稱以展開該區段。 新增任何必要的參數,然後選取 [試試看!]

Example Swagger GET test

注意

用於螢幕擷取畫面的 Swagger UI 版本為第 2 版。 如需第 3 版的範例,請參閱 Petstore 範例

下一步