使用 openAPI 文件

使用 Swagger UI 進行本機臨機操作測試

根據預設，Microsoft.AspNetCore.OpenApi 套件不會隨附內建支援，以支援將 OpenAPI 文件視覺化或與該文件互動。 用於視覺化或與 OpenAPI 文件互動的熱門工具包括 Swagger UI 和 ReDoc。 Swagger UI 和 ReDoc 可以透過數種方式整合在應用程式中。 Visual Studio 和 VS Code 等編輯器提供延伸模組和內建體驗，以針對 OpenAPI 文件進行測試。

Swashbuckle.AspNetCore.SwaggerUi 套件提供 Swagger UI Web 資產組合，以用於應用程式。 此套件可以用來呈現所產生文件的 UI。 若要進行此設定：

• 安裝 Swashbuckle.AspNetCore.SwaggerUi 套件。
• 透過參考稍早註冊的 OpenAPI 路由來啟用 swagger-ui 中介軟體。

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });

}

app.MapGet("/", () => "Hello world!");

app.Run();

基於限制資訊洩漏的安全性最佳做法， OpenAPI 使用者介面（Swagger UI、ReDoc、Scalar）應該只在開發環境中啟用。 例如，請參閱 Swagger OAuth 2.0 組態。

啟動應用程式並流覽至 https://localhost:<port>/swagger 以檢視 Swagger UI。

要在 Swagger UI URL 上使用 https 的 Properties/launchSettings.json 設定檔自動啟動應用程式：

• launchBrowser確認已啟用 （true）。
• 將 launchUrl 設定為 swagger。

"launchBrowser": true,
"launchUrl": "swagger",

將 Scalar 用於互動式 API 文件

Scalar 是 OpenAPI 的開放原始碼互動式文件 UI。 Scalar 可以與 ASP.NET Core 所提供的 OpenAPI 端點整合。 若要設定純量，請安裝 Scalar.AspNetCore 套件。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

app.MapGet("/", () => "Hello world!");

app.Run();

啟動應用程式並導航至 https://localhost:<port>/scalar/v1 以檢視純量使用者介面。

若要使用 https 設定檔 Properties/launchSettings.json，自動在 Scalar UI URL 上啟動應用程式：

• launchBrowser確認已啟用 （true）。
• 將 launchUrl 設定為 scalar/v1。

"launchBrowser": true,
"launchUrl": "scalar/v1",

Lint 透過 Spectral 產生的 OpenAPI 文件

Spectral 是開放原始碼 OpenAPI 文件 Linter。 Spectral 可以納入應用程式組建中，以驗證產生的 OpenAPI 文件品質。 根據套件安裝指示安裝 Spectral。

若要利用 Spectral，請安裝 Microsoft.Extensions.ApiDescription.Server 套件以啟用建置階段 OpenAPI 文件產生。

在應用程式的 .csproj 檔案中設定下列屬性，以在建置階段啟用文件產生：

<PropertyGroup>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>

執行 dotnet build 以產生文件。

dotnet build

使用下列內容建立 .spectral.yml 檔案。

extends: ["spectral:oas"]

在產生的檔案上執行 spectral lint。

spectral lint WebMinOpenApi.json
...

The output shows any issues with the OpenAPI document. For example:

```output
1:1  warning  oas3-api-servers       OpenAPI "servers" must be present and non-empty array.
3:10  warning  info-contact           Info object must have "contact" object.                        info
3:10  warning  info-description       Info "description" must be present and non-empty string.       info
9:13  warning  operation-description  Operation "description" must be present and non-empty string.  paths./.get
9:13  warning  operation-operationId  Operation must have "operationId".                             paths./.get

✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)