Swagger (OpenAPI)
をテンプレートにして作成
[
トップ
] [
新規
|
一覧
|
単語検索
|
最終更新
|
ヘルプ
]
開始行:
「[[マイクロソフト系技術情報 Wiki>http://techinfoofmicros...
-[[戻る>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サービスを作成する方法#y40ce14...
**言語毎の実装 [#z57706c5]
-各言語のドキュメントファイルから、Swagger Spec Files（Js...
-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]
*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]
-[[Swashbuckle.Core>https://www.nuget.org/packages/Swashb...
Install-Package Swashbuckle.Core
-プロジェクトのプロパティで、XML ドキュメントファイルのパ...
--プロジェクトのプロパティをクリック
--左ペインで「ビルド」を選択
--「XML ドキュメント ファイル」のチェックボックスをオン。
--パスが表示される（このパスは後で使います）。
-Startup クラスで Swashbuckle の構成を設定
// Swashbuckle の構成
config.EnableSwagger(c =>
{
c.SingleApiVersion("v1.0", "WebApplication");
c.IncludeXmlComments(System.AppDomain.CurrentDomain.Bas...
})
.EnableSwaggerUi(c => { });
-「/swagger/ui/index」にアクセスする。~
すると、Swagger UI のドキュメントページが表示される。
***不明点 [#te402fd1]
[[モデル・バインディング>ASP.NET Web API#rfb25f2f]]の仕様...
ASP.NETのメソッド・シグネチャだけで、自動生成だけでイケる...
XMLコメントの書き方などにルールなどはないのかなぁ？などと...
-ModelBinder caused complex type to display property-by-p...
5.2.2 · Issue #536 · domaindrivendev/Swashbuckle~
https://github.com/domaindrivendev/Swashbuckle/issues/536
-c# - Swashbuckle and Web Api method with ModelBinder - S...
http://stackoverflow.com/questions/30429592/swashbuckle-a...
ざっと見たところ、[FromBody] や [FromUri] などの属性で、~
絞ることで、Web APIの仕様も明確になるものと思われる。
**Microsoft.AspNet.WebApi.HelpPage [#ae85e3ae]
https://www.nuget.org/packages/Microsoft.AspNet.WebApi.He...
コチラのツールは、[[ASP.NET MVC]]への依存が欠点とされる。
-IIS 以外の環境でホストできない（[[ASP.NET Web API]]はセ...
-[[.NET Core]]に対応していない（[[.NET Standard]]の文字が...
-[[ASP.NET MVC]]のレスポンスとしてしかドキュメントを確認...
以下のドキュメント出力機能を持つ。
-XML コメントが適用される
-出力のカスタマイズが可能
-実装コードと同期
-APIテストが可能
*参考 [#u2c42496]
-RESTful APIの記述標準化を目指す「Open API Initiative」を~
マイクロソフト、Google、IBMらが立ち上げ。Swaggerをベース...
http://www.publickey1.jp/blog/15/open_api_initiative.html
-Swagger が OpenAPI にリネームされて~
Open API Initiative が誕生してた~
https://r2.ag/swagger-to-openapi/
-Swagger / OpenAPI 定義から~
C# クライアントを自動生成するツールの比較 - しばやん雑記~
https://blog.shibayan.jp/entry/20190610/1560150929
**ASP.NET [#m5765aff]
「新」はSwagger 2.0 ≒ OpenAPI 2.0
***新 [#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-...
***旧 [#d6b4a2e4]
-Swagger を使った ASP.NET Web API のドキュメント生成 - mi...
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)を使う -...
http://beachside.hatenablog.com/entry/2015/05/31/202348
**ASP.NET Core [#xcbdb1f3]
「新」はSwagger 2.0 ≒ OpenAPI 2.0
***新 [#i188650f]
-ASP.NET CoreアプリでSwaggerを導入する - noxi雑記~
https://noxi515.hateblo.jp/entry/2018/03/11/191744
-ASP.NET Core 2.0 でも Swashbuckle.AspNetCore は使えた - ...
https://tnakamura.hatenablog.com/entry/2017/08/23/swashbu...
***旧 [#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
**Microsoft Docs [#aeb0086a]
-Swagger / Open API を使用する ASP.NET Core Web API のヘ...
https://docs.microsoft.com/ja-jp/aspnet/core/tutorials/we...
-Swashbuckle が生成する API 定義をカスタマイズする~
https://docs.microsoft.com/ja-jp/azure/app-service-api/ap...
----
Tags: [[:IT国際標準]], [[:プログラミング]], [[:通信技術]]...
終了行:
「[[マイクロソフト系技術情報 Wiki>http://techinfoofmicros...
-[[戻る>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サービスを作成する方法#y40ce14...
**言語毎の実装 [#z57706c5]
-各言語のドキュメントファイルから、Swagger Spec Files（Js...
-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]
*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]
-[[Swashbuckle.Core>https://www.nuget.org/packages/Swashb...
Install-Package Swashbuckle.Core
-プロジェクトのプロパティで、XML ドキュメントファイルのパ...
--プロジェクトのプロパティをクリック
--左ペインで「ビルド」を選択
--「XML ドキュメント ファイル」のチェックボックスをオン。
--パスが表示される（このパスは後で使います）。
-Startup クラスで Swashbuckle の構成を設定
// Swashbuckle の構成
config.EnableSwagger(c =>
{
c.SingleApiVersion("v1.0", "WebApplication");
c.IncludeXmlComments(System.AppDomain.CurrentDomain.Bas...
})
.EnableSwaggerUi(c => { });
-「/swagger/ui/index」にアクセスする。~
すると、Swagger UI のドキュメントページが表示される。
***不明点 [#te402fd1]
[[モデル・バインディング>ASP.NET Web API#rfb25f2f]]の仕様...
ASP.NETのメソッド・シグネチャだけで、自動生成だけでイケる...
XMLコメントの書き方などにルールなどはないのかなぁ？などと...
-ModelBinder caused complex type to display property-by-p...
5.2.2 · Issue #536 · domaindrivendev/Swashbuckle~
https://github.com/domaindrivendev/Swashbuckle/issues/536
-c# - Swashbuckle and Web Api method with ModelBinder - S...
http://stackoverflow.com/questions/30429592/swashbuckle-a...
ざっと見たところ、[FromBody] や [FromUri] などの属性で、~
絞ることで、Web APIの仕様も明確になるものと思われる。
**Microsoft.AspNet.WebApi.HelpPage [#ae85e3ae]
https://www.nuget.org/packages/Microsoft.AspNet.WebApi.He...
コチラのツールは、[[ASP.NET MVC]]への依存が欠点とされる。
-IIS 以外の環境でホストできない（[[ASP.NET Web API]]はセ...
-[[.NET Core]]に対応していない（[[.NET Standard]]の文字が...
-[[ASP.NET MVC]]のレスポンスとしてしかドキュメントを確認...
以下のドキュメント出力機能を持つ。
-XML コメントが適用される
-出力のカスタマイズが可能
-実装コードと同期
-APIテストが可能
*参考 [#u2c42496]
-RESTful APIの記述標準化を目指す「Open API Initiative」を~
マイクロソフト、Google、IBMらが立ち上げ。Swaggerをベース...
http://www.publickey1.jp/blog/15/open_api_initiative.html
-Swagger が OpenAPI にリネームされて~
Open API Initiative が誕生してた~
https://r2.ag/swagger-to-openapi/
-Swagger / OpenAPI 定義から~
C# クライアントを自動生成するツールの比較 - しばやん雑記~
https://blog.shibayan.jp/entry/20190610/1560150929
**ASP.NET [#m5765aff]
「新」はSwagger 2.0 ≒ OpenAPI 2.0
***新 [#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-...
***旧 [#d6b4a2e4]
-Swagger を使った ASP.NET Web API のドキュメント生成 - mi...
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)を使う -...
http://beachside.hatenablog.com/entry/2015/05/31/202348
**ASP.NET Core [#xcbdb1f3]
「新」はSwagger 2.0 ≒ OpenAPI 2.0
***新 [#i188650f]
-ASP.NET CoreアプリでSwaggerを導入する - noxi雑記~
https://noxi515.hateblo.jp/entry/2018/03/11/191744
-ASP.NET Core 2.0 でも Swashbuckle.AspNetCore は使えた - ...
https://tnakamura.hatenablog.com/entry/2017/08/23/swashbu...
***旧 [#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
**Microsoft Docs [#aeb0086a]
-Swagger / Open API を使用する ASP.NET Core Web API のヘ...
https://docs.microsoft.com/ja-jp/aspnet/core/tutorials/we...
-Swashbuckle が生成する API 定義をカスタマイズする~
https://docs.microsoft.com/ja-jp/azure/app-service-api/ap...
----
Tags: [[:IT国際標準]], [[:プログラミング]], [[:通信技術]]...
ページ名:
![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
