Open棟梁Project - マイクロソフト系技術情報 Wiki
目次 †
概要 †
- REST API を定義するための仕様。
- 色々な自動化のために利用される。
- Swagger 2.0 仕様は OpenAPI 2.0 仕様としてリネームされた。
開発手順 †
- 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 †
概要 †
利用手順 †
- プロジェクトのプロパティで、XML ドキュメントファイルのパスを設定
- プロジェクトのプロパティをクリック
- 左ペインで「ビルド」を選択
- 「XML ドキュメント ファイル」のチェックボックスをオン。
- パスが表示される(このパスは後で使います)。
- 「/swagger/ui/index」にアクセスする。
すると、Swagger UI のドキュメントページが表示される。
不明点 †
モデル・バインディングの仕様がカオスだから、自動生成だけでイケる気がしない。
XMLコメントの書き方などにルールなどはないのかなぁ?などと思った。
この辺か?
ざっと見たところ、[FromBody?] や [FromUri?] などの属性で、
絞ることで、Web APIの仕様も明確になるものと思われる。
Microsoft.AspNet?.WebApi?.HelpPage? †
https://www.nuget.org/packages/Microsoft.AspNet.WebApi.HelpPage
ASP.NET MVCへの依存が欠点とされる。
以下のドキュメント出力機能を持つ。
- XML コメントが適用される
- 出力のカスタマイズが可能
- 実装コードと同期
- APIテストが可能
参考 †
- ROMANCE DAWN for the new world
Tags: :.NET開発, :.NET Core, :ASP.NET, :ASP.NET Web API