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

目次

概要

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

開発手順

  • 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を組み合わせる。

利用手順

  • プロジェクトのプロパティで、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コメントの書き方などにルールなどはないのかなぁ?などと思った。

ざっと見たところ、[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テストが可能

参考

ASP.NET

ASP.NET Core

Microsoft Docs


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


トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2018-10-09 (火) 22:29:04 (9d)