[[Open棟梁Project>http://opentouryo.osscons.jp/]] - [[マイクロソフト系技術情報 Wiki>http://techinfoofmicrosofttech.osscons.jp/]] -[[戻る>.NET開発]] * 目次 [#g017f65e] #contents *概要 [#y52c6396] -RESTful API のドキュメントや説明の際に利用される、~ 仕様とフレームワークとツール群から成り立つ。 -[[Microsoft.AspNet.WebApi.HelpPage>#zb96ff92]]の欠点をカバーできる。 -言語、プラットフォームに依存しない --Swagger の仕様に準じた RESTful API のインターフェイスであれば、~ Swagger Spec Files(Json)という、API のドキュメントが生成・提供できる。 --これにより、特定のプラットフォームに依存しないデータ交換が可能。~ ([[ココ>JSONを送受信するRESTサービスを作成する方法#y40ce141]]で言った、データコントラクトにJSONフォーマットを使用するのと同じ手法) -OpenAPI仕様~ https://github.com/OAI/OpenAPI-Specification *ツール [#ead45b3a] http://swagger.io/open-source-integrations/ **言語毎の実装 [#j9b7cb53] -各言語のドキュメントファイルから、Swagger Spec Files(Json)生成 -Swagger Spec Files(Json)からのクライアントコード生成。 **swagger-ui [#k3783c7f] Swagger Spec Files(Json)を参照し、クライアントとして機能する。 **swagger-editor [#oc412dda] -YAML で API のドキュメントを記述 -リアルタイムで Swagger UI をプレビュー -また、YAML からSwagger Spec Filesを出力できる。 **swagger-codegen [#yf9f33b6] Json ファイルからクライアントコードを生成する。 *Swashbuckle [#ce9f1d83] **概要 [#vee91a65] -[[ASP.NET Web API]]向けのドキュメント生成する。 --WebApiプロジェクトにSwaggerをシームレスに追加する。 --ApiExplorer(.NET)と、Swagger / swagger-uiを組み合わせる。 -プロジェクト・サイト --https://github.com/domaindrivendev/Swashbuckle --https://github.com/domaindrivendev/Swashbuckle.AspNetCore **利用手順 [#bfaf5f17] -[[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 のドキュメントページが表示される。 **不明点 [#sab65e58] モデル・バインディングの仕様がカオスだから、自動生成だけでイケる気がしない。~ 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 [#zb96ff92] https://www.nuget.org/packages/Microsoft.AspNet.WebApi.HelpPage 以下のドキュメント出力機能を持つ。 -XML コメントが適用される -出力のカスタマイズが可能 -実装コードと同期 -APIテストが可能 [[ASP.NET MVC]]への依存が欠点とされる。 -IIS 以外の環境でホストできない([[ASP.NET Web API]]はセルフホストが可能) -[[.NET Core]]に対応していない(.NETStandardの文字が見えない)。 -[[ASP.NET MVC]]のレスポンスとしてしかドキュメントを確認できない。 *参考 [#r27b657d] -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 ---- Tags: [[:.NET開発]], [[:.NET Core]], [[:ASP.NET]], [[:ASP.NET Web API]]