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

追加された行はこの色です。
削除された行はこの色です。
「[[マイクロソフト系技術情報 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 [#i27b2f73]

**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]
***利用手順 [#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]
***不明点 [#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]
**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の文字が見えない）。
-[[.NET Core]]に対応していない（[[.NET Standard]]の文字が見えない）。
-[[ASP.NET MVC]]のレスポンスとしてしかドキュメントを確認できない。

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

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

*参考 [#u2c42496]
-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/

**ASP.NET [#m5765aff]

***新 [#e8e61964]
-【連載】ASP.NET Web API を使おう： - nuits.jp blog
--第1回 Web APIを作成する~
http://www.nuits.jp/entry/web-api-hello-web-api
--第2回 Swaggerを適用する~
http://www.nuits.jp/entry/web-api-apply-swagger
--第3回 swagger-codegenでクライアントコードを生成する~
http://www.nuits.jp/entry/web-api-swagger-codegen

-How to Setup Swagger in Web API ASP.NET with Swashbuckle~
https://www.andrewhoefling.com/Home/post/web-api-swagger-swashbuckle

***旧 [#d6b4a2e4]
-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~
**ASP.NET Core [#xcbdb1f3]

***新 [#i188650f]
-ASP.NET CoreアプリでSwaggerを導入する - noxi雑記~
https://noxi515.hateblo.jp/entry/2018/03/11/191744
-ASP.NET Core 2.0 でも Swashbuckle.AspNetCore は使えた - present~
https://tnakamura.hatenablog.com/entry/2017/08/23/swashbuckle-aspnetcore

***旧 [#z72f5806]
-ASP.NET Core で作成した Web API のドキュメントを Swagger を使って生成する~
http://qiita.com/t-koyama/items/02571ac025cc54f0dbcb
-ASP.NET CoreでSwaggerを使う~
https://qiita.com/taiga_takahari/items/a3f1c5500937854bb49e

-Swashbuckle が生成する API 定義をカスタマイズする | Microsoft Docs~
**Microsoft Docs [#aeb0086a]
-Swagger / Open API を使用する ASP.NET Core Web API のヘルプ ページ~
https://docs.microsoft.com/ja-jp/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-2.1

-Swashbuckle が生成する API 定義をカスタマイズする~
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]]