「[[マイクロソフト系技術情報 Wiki>http://techinfoofmicrosofttech.osscons.jp/]]」は、「[[Open棟梁Project>https://github.com/OpenTouryoProject/]]」,「[[OSSコンソーシアム .NET開発基盤部会>https://www.osscons.jp/dotNetDevelopmentInfrastructure/]]」によって運営されています。 -[[戻る>WebAPI]] * 目次 [#cc73c7cf] #contents *概要 [#t8a6a81c] -[[REST]]ful API を定義するための仕様。 -色々な自動化のために利用される。 -Swagger 2.0 仕様は OpenAPI 2.0 仕様としてリネームされた。 --OpenAPI仕様~ https://github.com/OAI/OpenAPI-Specification -[[Microsoft.AspNet.WebApi.HelpPage>#ae85e3ae]] --HelpPageの欠点をカバーできる。 --また、HelpPageよりも多機能。 *開発手順 [#zeab0f44] -Swaggerの仕様に沿ってWebAPIを設計、 -エディタを使い定義書(YAML/JSON)を作成。 -定義書のバリデーションを行なう。 -各種の自動生成が可能。 --ドキュメント --モック --クライアント --テスト -入出力のバリデーションをフレームワークで処理。 *ツール [#eca90915] http://swagger.io/open-source-integrations/ -自動化のためのツール・フレームワーク群が存在する。 --定義書エディタ --定義書のバリデーション --色々と自動生成(ドキュメント・モック・クライアント・テスト) --入出力のバリデーション -言語、プラットフォームに依存しない --Swagger の仕様に準じた [[REST]]ful API のインターフェイスであれば、~ Swagger Spec Filesという、WebAPI 定義書を自動生成・提供できる。 --これにより、特定のプラットフォームに依存しないデータ交換が可能。~ ([[ココ>JSONを送受信するRESTサービスを作成する方法#y40ce141]]で言った、データコントラクトにJSONフォーマットを使用するのと同じ手法) **言語毎の実装 [#z57706c5] -各言語のドキュメントファイルから、Swagger Spec Files(Json)生成 -Swagger Spec Files(Json)からのクライアントコード生成。 **swagger-ui [#g42a0c52] Swagger Spec Files(Json)を参照し、クライアントとして機能する。 **swagger-editor [#o054378e] -YAML で API のドキュメントを記述 -リアルタイムで Swagger UI をプレビュー -また、YAML からSwagger Spec Filesを出力できる。 **swagger-codegen [#se638e58] Json ファイルからクライアントコードを自動生成する。 **, etc. [#j62dd3bf] *Swashbuckle [#de1abbbf] **概要 [#q7243bb1] -[[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 **利用手順 [#hfcb68c0] -[[Swashbuckle.Core>https://www.nuget.org/packages/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 のドキュメントページが表示される。 **不明点 [#te402fd1] モデル・バインディングの仕様がカオスだから、自動生成だけでイケる気がしない。~ 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 [#ae85e3ae] 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テストが可能 *参考 [#u2c42496] -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]]