1. はじめに
OpenAPI は、REST API を記述するための言語に依存しない仕様です。これにより、コンピューターとユーザーは、ソース コードに直接アクセスしなくても、REST API の機能を理解できるようになります。その主な目的は次のとおりです。
- 別々のサービスを接続するために必要な労力を最小限に抑えます。
- サービスを正確に文書化するために必要な時間を短縮します。
要するに：
- OpenAPI は仕様です。
- Swagger は、OpenAPI 仕様を使用するツールです。たとえば、OpenAPIGenerator Swashbuckle や SwaggerUI などです。
2.スワッシュバックルの使用
asp.net core に基づく Web API アプリケーションがすでに存在すると仮定し、具体的な作成プロセスについては
https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/first-web-api?view=aspnetcore-3.1&tabs=visual-studio
を参照してください。 この記事では、MvcMovie を例として取り上げます。
ソリューション エクスプローラーでプロジェクトを右クリックし、
[NuGet パッケージの管理] 検索ボックスに「Swashbuckle.AspNetCore」
と入力します。 [参照] タブから最新の「Swashbuckle.AspNetCore」パッケージを選択し、[インストール] をクリックします。
2. Swagger ミドルウェアを追加して構成する
Swagger ジェネレーターを Startup.ConfigureServices メソッドのサービス コレクションに追加します。
public void ConfigureServices(IServiceCollection services)
{
// Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen();
......
} Startup.Configure メソッドで、ミドルウェアが生成された JSON ドキュメントと Swagger UI を提供できるようにします。
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
// Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();
// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
// specifying the Swagger JSON endpoint.
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API V1");
});
......
}アプリケーションを実行してドキュメントと UI インターフェイスにアクセスします
ドキュメンテーション
3. API 情報と説明
AddSwaggerGen メソッドに渡される構成操作により、作成者、ライセンス、説明などの情報が追加されます。
Startup クラスで、OpenApiInfo クラスを使用するために次の名前空間をインポートします。
using Microsoft.OpenApi.Models;
public void ConfigureServices(IServiceCollection services)
{
// Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "MvcMovie API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = new Uri("https://example.com/terms"),
Contact = new OpenApiContact
{
Name = "阿波罗",
Email = string.Empty,
Url = new Uri("https://twitter.com/zhoujyer"),
},
License = new OpenApiLicense
{
Name = "Use under LICX",
Url = new Uri("https://example.com/license"),
}
});
});
......
}Swagger UI によって表示されるバージョン情報は次のとおりです。
3. 自動コード生成
1. NSwag は次の機能を提供します。
Swagger UI および Swagger ジェネレーターを使用する機能。
柔軟なコード生成機能。
NSwag を使用すると、既存の API を使用する必要がありません。つまり、Swagger を含むサードパーティ API を使用して、クライアント実装を生成できます。NSwag を使用すると、開発サイクルをスピードアップし、API の変更に簡単に適応できます。
2. NSwagミドルウェアのインストールと登録
ソリューション エクスプローラーでプロジェクトを右クリックし、[NuGet パッケージの管理]
検索ボックスに「NSwag.AspNetCore」
と入力します。 [参照] タブから「NSwag.AspNetCore」パッケージを選択し、[インストール] をクリックします。
Startup.ConfigureServices メソッドで、必要な Swagger サービスを登録します。
public void ConfigureServices(IServiceCollection services)
{
// Register the Swagger services
services.AddSwaggerDocument();
......
}Startup.Configure メソッドで、生成された Swagger 仕様と Swagger UI を提供するミドルウェアを有効にします。
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
// Register the Swagger generator and the Swagger UI middlewares
app.UseOpenApi();
app.UseSwaggerUi3();
......
}3. NSwagStudio ツールをダウンロードしてインストールします
https://github.com/RicoSuter/NSwag/wiki/NSwagStudio
4. NSwagStudioを実行する
「仕様 URL」に OpenAPI ドキュメントの URL を入力し、「ローカル コピーの作成」をクリックします。
右側のウィンドウで Typescript クライアントまたは CSharp クライアントを選択すると、Typescript または C# で使用されるクライアント コードが自動的に生成され、開発効率が向上します。
4. 参考資料
https://docs.microsoft.com/zh-cn/aspnet/core/web-api/?view=aspnetcore-3.1