Swagger (OpenAPI) のバックアップ(No.12)

[ トップ ]   [ 新規 | 一覧 | 単語検索 | 最終更新 | ヘルプ ]

• バックアップ一覧
• 差分 を表示
• 現在との差分 を表示
• ソース を表示
• Swagger (OpenAPI) へ行く。
  • 1 (2017-01-29 (日) 22:27:18)
  • 2 (2017-01-30 (月) 00:43:40)
  • 3 (2017-01-30 (月) 02:29:31)
  • 4 (2017-01-30 (月) 10:06:20)
  • 5 (2017-03-09 (木) 09:15:16)
  • 6 (2017-05-04 (木) 18:18:48)
  • 7 (2017-05-07 (日) 17:19:15)
  • 8 (2017-06-18 (日) 21:37:49)
  • 9 (2017-09-25 (月) 14:54:40)
  • 10 (2018-09-28 (金) 18:53:11)
  • 11 (2018-10-01 (月) 10:07:34)
  • 12 (2018-10-09 (火) 22:29:04)

---

「マイクロソフト系技術情報 Wiki」は、「Open棟梁Project」,「OSSコンソーシアム .NET開発基盤部会」によって運営されています。

• 戻る

目次 †

概要 †

• RESTful API を定義するための仕様。
• 色々な自動化のために利用される。

• Swagger 2.0 仕様は OpenAPI 2.0 仕様としてリネームされた。
  • OpenAPI仕様
    https://github.com/OAI/OpenAPI-Specification

• Microsoft.AspNet.WebApi.HelpPage
  • HelpPage?の欠点をカバーできる。
  • また、HelpPage?よりも多機能。

開発手順 †

• Swaggerの仕様に沿ってWebAPIを設計、
• エディタを使い定義書（YAML/JSON）を作成。
• 定義書のバリデーションを行なう。
• 各種の自動生成が可能。
  • ドキュメント
  • モック
  • クライアント
  • テスト
• 入出力のバリデーションをフレームワークで処理。

ツール †

http://swagger.io/open-source-integrations/

• 自動化のためのツール・フレームワーク群が存在する。
  • 定義書エディタ
  • 定義書のバリデーション
  • 色々と自動生成（ドキュメント・モック・クライアント・テスト）
  • 入出力のバリデーション

• 言語、プラットフォームに依存しない
  • Swagger の仕様に準じた RESTful API のインターフェイスであれば、
    Swagger Spec Filesという、WebAPI 定義書を自動生成・提供できる。
  • これにより、特定のプラットフォームに依存しないデータ交換が可能。
    （ココで言った、データコントラクトにJSONフォーマットを使用するのと同じ手法）

言語毎の実装 †

• 各言語のドキュメントファイルから、Swagger Spec Files（Json）生成
• Swagger Spec Files（Json）からのクライアントコード生成。

swagger-ui †

Swagger Spec Files（Json）を参照し、クライアントとして機能する。

swagger-editor †

• YAML で API のドキュメントを記述
• リアルタイムで Swagger UI をプレビュー
• また、YAML からSwagger Spec Filesを出力できる。

swagger-codegen †

Json ファイルからクライアントコードを自動生成する。

, etc. †

ASP.NET †

Swashbuckle †

概要 †

• 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

利用手順 †

• 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 のドキュメントページが表示される。

不明点 †

モデル・バインディングの仕様がカオス（と言うかファジー）だから、
ASP.NETのメソッド・シグネチャだけで、自動生成だけでイケる気がしない。
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? †

https://www.nuget.org/packages/Microsoft.AspNet.WebApi.HelpPage

コチラのツールは、ASP.NET MVCへの依存が欠点とされる。

• IIS 以外の環境でホストできない（ASP.NET Web APIはセルフホストが可能）
• .NET Coreに対応していない（.NET Standardの文字が見えない）。
• ASP.NET MVCのレスポンスとしてしかドキュメントを確認できない。

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

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

参考 †

• 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 †

新 †

• 【連載】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

旧 †

• 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 †

新 †

• 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

旧 †

• 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 †

• 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

---

Tags: :IT国際標準, :プログラミング, :通信技術, :.NET開発, :.NET Core, :ASP.NET, :ASP.NET Web API

     

Site admin: dotNetDevelopmentInfrastructure

PukiWiki 1.4.7 Copyright © 2001-2006 PukiWiki Developers Team. License is GPL.
Based on "PukiWiki" 1.3 by yu-ji. Powered by PHP 5.3.3. HTML convert time: 0.032 sec.