Skip to content

MS_SwaggerOpenAPI

Jump to bottom
nishi_74322014 edited this page Aug 3, 2026 · 1 revision

Swagger (OpenAPI)

概要

  • RESTful API を定義するための仕様。

  • 色々な自動化のために利用される。

  • Swagger 2.0 仕様は OpenAPI 2.0 仕様としてリネームされた。

  • Microsoft.AspNet.WebApi.HelpPage の欠点をカバーできる。また、HelpPage よりも多機能。

補足（最新化）: 用語の整理をしておく。

語 指すもの
OpenAPI Specification (OAS) 仕様そのもの。2.0 → 3.0 → 3.1 と進んだ
Swagger SmartBear 社のツール群の名称（Swagger UI / Editor / Codegen）

「Swagger ファイル」という言い方が残っているが、 仕様名としては OpenAPI が正しい。 OpenAPI 3.1 で JSON Schema との完全互換が達成された。

開発手順

  • Swagger の仕様に沿って WebAPI を設計
  • エディタを使い定義書（YAML/JSON）を作成
  • 定義書のバリデーションを行なう
  • 各種の自動生成が可能
    • ドキュメント
    • モック
    • クライアント
    • テスト
  • 入出力のバリデーションをフレームワークで処理

補足: 上記は「定義書を先に書く（design-first）」流れである。 対して .NET でよく行われるのは「実装から定義書を生成する」 （code-first）流れで、両者は運用が大きく変わる。

  • design-first — 定義書がフロント／バックの契約になる。並行開発しやすい
  • code-first — 実装とのズレが出にくいが、実装が固まるまで契約が定まらない

チームを跨ぐ API では design-first が向く。

ツール

Swagger Open Source Integrations

  • 自動化のためのツール・フレームワーク群が存在する。

    • 定義書エディタ
    • 定義書のバリデーション
    • 色々と自動生成（ドキュメント・モック・クライアント・テスト）
    • 入出力のバリデーション

  • 言語、プラットフォームに依存しない

    • Swagger の仕様に準じた RESTful API のインターフェイスであれば、
      Swagger Spec Files という、WebAPI 定義書を自動生成・提供できる。
    • これにより、特定のプラットフォームに依存しないデータ交換が可能
      （JSONを送信するRESTサービスを作成する方法（MS_JSONRestService.md）で言った、
      データコントラクトに JSON フォーマットを使用するのと同じ手法）。
ツール 役割
swagger-ui Swagger Spec Files（JSON）を参照し、クライアントとして機能する
swagger-editor YAML で API のドキュメントを記述。リアルタイムで Swagger UI をプレビュー。YAML から Spec Files を出力できる
swagger-codegen JSON ファイルからクライアントコードを自動生成する

言語毎の実装

  • 各言語のドキュメントファイルから、Swagger Spec Files（JSON）生成
  • Swagger Spec Files（JSON）からのクライアントコード生成

ASP.NET

Swashbuckle

概要

利用手順

  • Swashbuckle.Core を NuGet からインストール

    Install-Package Swashbuckle.Core

  • プロジェクトのプロパティで、XML ドキュメントファイルのパスを設定

    • プロジェクトのプロパティをクリック
    • 左ペインで「ビルド」を選択
    • 「XML ドキュメント ファイル」のチェックボックスをオン
    • パスが表示される（このパスは後で使う）

  • Startup クラスで Swashbuckle の構成を設定

    // Swashbuckle の構成
config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1.0", "WebApplication");
    c.IncludeXmlComments(System.AppDomain.CurrentDomain.BaseDirectory + @"bin\WebApplication.XML");
})
.EnableSwaggerUi(c => { });

  • 「/swagger/ui/index」にアクセスする。
    すると、Swagger UI のドキュメントページが表示される。

不明点

モデル・バインディング（ASP.NET Web API）の仕様がカオス
（と言うかファジー）だから、
ASP.NET のメソッド・シグネチャだけで、自動生成だけでイケる気がしない。
XML コメントの書き方などにルールなどはないのかなぁ？などと思った。

ざっと見たところ、[FromBody] や [FromUri] などの属性で
絞ることで、Web API の仕様も明確になるものと思われる。

補足: この点は現在も本質的に変わっていない。 型と属性で表現されていない情報は定義書に出ないためである。 対策としては次が有効である。

  • パラメータのバインド元を [FromBody] / [FromQuery] / [FromRoute] で明示する
  • 戻り値を ActionResult<T> にする、または [ProducesResponseType(typeof(Foo), StatusCodes.Status200OK)] を付ける
  • リクエスト／レスポンスを匿名型や object にしない

Microsoft.AspNet.WebApi.HelpPage

NuGet - Microsoft.AspNet.WebApi.HelpPage

コチラのツールは、ASP.NET MVC（MS_ASPNETMVC.md）への依存が欠点とされる。

  • IIS 以外の環境でホストできない（ASP.NET Web API はセルフホストが可能）
  • .NET Core（MS_DotNetCore.md）に対応していない（.NET Standard（MS_DotNetStandard.md）の文字が見えない）
  • ASP.NET MVC のレスポンスとしてしかドキュメントを確認できない

以下のドキュメント出力機能を持つ。

  • XML コメントが適用される
  • 出力のカスタマイズが可能
  • 実装コードと同期
  • API テストが可能

ASP.NET Coreの現状

補足（最新化）: .NET 9 以降、Web API テンプレートから Swashbuckle が外れた。標準は Microsoft 製の Microsoft.AspNetCore.OpenApi パッケージ（AddOpenApi / MapOpenApi）で、 OpenAPI ドキュメントの生成のみを行う。

builder.Services.AddOpenApi();
// ...
app.MapOpenApi();   // /openapi/v1.json

UI は同梱されないため、画面が必要なら Scalar や Swagger UI を別途追加する。 Swashbuckle 自体はメンテナンスが停滞していた時期があり、 代替として NSwag も広く使われている。

参考

Tags: IT国際標準, プログラミング, 通信技術, .NET開発, .NET Core, ASP.NET, ASP.NET Web API

このWikiは「Open棟梁Project」,「OSSコンソーシアム 開発基盤部会」によって運営されています。

NetDevInfraWiki

マイクロソフト系技術情報 Wiki
Open 棟梁 Wiki

（未着手）

開発基盤部会 Wiki

移行管理: DONE ／ TODO

Clone this wiki locally