Swagger のバックアップの現在との差分(No.2) - マイクロソフト系技術情報 Wiki

バックアップ一覧
ソースを表示
バックアップを表示
Swagger は削除されています。
- 1 (2017-01-29 (日) 18:50:29)
- 2 (2017-01-29 (日) 20:57:04)
追加された行はこの色です。
削除された行はこの色です。
[[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]]