Swagger (OpenAPI) のバックアップ(No.9) - マイクロソフト系技術情報 Wiki

「マイクロソフト系技術情報 Wiki」は、「Open棟梁Project」,「OSSコンソーシアム .NET開発基盤部会」によって運営されています。

戻る

目次 †

目次
概要
開発手順
ツール
Swashbuckle
Microsoft.AspNet.WebApi.HelpPage
参考

↑

概要 †

RESTful API を定義するための仕様。
色々な自動化のために利用される。

Swagger 2.0 仕様は OpenAPI 2.0 仕様としてリネームされた。
- OpenAPI仕様
  https://github.com/OAI/OpenAPI-Specification

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

↑

開発手順 †

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

↑

ツール †

http://swagger.io/open-source-integrations/

自動化のためのツール・フレームワーク群が存在する。
- 定義書エディタ
- 定義書のバリデーション
- 色々と自動生成（ドキュメント・モック・クライアント・テスト）
- 入出力のバリデーション

言語、プラットフォームに依存しない
- Swagger の仕様に準じた RESTful API のインターフェイスであれば、
  Swagger Spec Filesという、WebAPI 定義書を自動生成・提供できる。
- これにより、特定のプラットフォームに依存しないデータ交換が可能。
  （ココで言った、データコントラクトにJSONフォーマットを使用するのと同じ手法）

↑

言語毎の実装 †

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

↑

swagger-ui †

Swagger Spec Files（Json）を参照し、クライアントとして機能する。

↑

swagger-editor †

YAML で API のドキュメントを記述
リアルタイムで Swagger UI をプレビュー
また、YAML からSwagger Spec Filesを出力できる。

↑

swagger-codegen †

Json ファイルからクライアントコードを自動生成する。

↑

, etc. †

↑

Swashbuckle †

↑

概要 †

ASP.NET Web API向けのSwaggerの部分的な実装。
- ASP.NET Web APIプロジェクトにSwaggerをシームレスに追加する。
- ApiExplorer?(.NET)と、Swagger / swagger-uiを組み合わせる。

プロジェクト・サイト
- https://github.com/domaindrivendev/Swashbuckle
- https://github.com/domaindrivendev/Swashbuckle.AspNetCore

↑

利用手順 †

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 のドキュメントページが表示される。

↑

不明点 †

モデル・バインディングの仕様がカオスだから、自動生成だけでイケる気がしない。
XMLコメントの書き方などにルールなどはないのかなぁ？などと思った。

この辺か？

ModelBinder? caused complex type to display property-by-property
5.2.2 · Issue #536 · domaindrivendev/Swashbuckle
https://github.com/domaindrivendev/Swashbuckle/issues/536

c# - Swashbuckle and Web Api method with ModelBinder? - Stack Overflow
http://stackoverflow.com/questions/30429592/swashbuckle-and-web-api-method-with-modelbinder

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

↑

Microsoft.AspNet?.WebApi?.HelpPage? †

https://www.nuget.org/packages/Microsoft.AspNet.WebApi.HelpPage

ASP.NET MVCへの依存が欠点とされる。

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

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

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

↑

参考 †

Swagger を使った ASP.NET Web API のドキュメント生成 - miso_soup3 Blog
http://miso-soup3.hateblo.jp/entry/2014/12/17/233409

ROMANCE DAWN for the new world
- Swagger 2.0 に対応した ASP.NET Web API のドキュメントを作成する
  http://gooner.hateblo.jp/entry/2015/12/08/011159
- ASP.NET Web API の Swagger ドキュメントからパラメータのモデル名を削除する
  http://gooner.hateblo.jp/entry/2016/07/27/063717

ASP.NET Web API2.2で、Swagger(Swashbuckle 5.1.5)を使う - BEACHSIDE BLOG
http://beachside.hatenablog.com/entry/2015/05/31/202348

ASP.NET Core で作成した Web API のドキュメントを Swagger を使って生成する - Qiita
http://qiita.com/t-koyama/items/02571ac025cc54f0dbcb

Swashbuckle が生成する API 定義をカスタマイズする | Microsoft Docs
https://docs.microsoft.com/ja-jp/azure/app-service-api/app-service-api-dotnet-swashbuckle-customize

RESTful APIの記述標準化を目指す「Open API Initiative」を
マイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに－ Publickey
http://www.publickey1.jp/blog/15/open_api_initiative.html
Swagger が OpenAPI にリネームされて Open API Initiative が誕生してた
https://r2.ag/swagger-to-openapi/

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