Swagger Tools で OpenAPI に準拠した API 設計

Swagger Tools で API 設計およびドキュメントを生成します。
今回は、OpenAPI 3.0 で定義してみます。

OpenAPI/Swagger

OpenAPI(Swagger) は API を記述する為の仕様です。
Swagger Specification は Linux Foundation に寄贈され、現在では OpenAPI Specification となり、OpenAPI Initiative によりプロジェクトが進められています。
Swagger 3.0 で構造もシンプルになり、より汎用性が高くなっています。

OpenAPI Initiative は Microsoft、Google、IBM、CapitalOne SmartBearなどの30以上の組織から結成されています。
SmartBear Software は Swagger の開発元であった Reverb Technologies を買収し、現在も Swagger Tooles を開発している企業です。

OpenAPI仕様

YAMLファイルで記述する際の、OpenAPI Object をみていきます。

  • openapi (必須)
    OpenAPI仕様バージョン
  • info (必須)
    APIに関するメタデータを表すオブジェクト
  • servers
    ターゲットサーバーへの接続情報を表すオブジェクト
  • paths (必須)
    APIで使用可能なパスと操作を表すオブジェクト
    個々のエンドポイントとその操作への相対パス
  • components
    仕様のさまざまなスキーマを表すオブジェクト
  • security
    API全体で使用できるセキュリティメカニズムを表すオブジェクト
  • tags
    追加のメタデータとともに仕様で使用されるタグを表すオブジェクト
  • externalDocs
    追加の外部ドキュメントを表すオブジェクト

こちらを記述する為の便利なツール(Swagger Editor)がありますので、そちらを使用してみます。

Swagger Tools

クラウド上で操作できる 統合環境の SwaggerHub もありますが、今回は Docker で構築してみます。

Swagger UI

Swagger UI はドキュメント化するツールです。
OpenAPI Specification 準拠の API からドキュメントを動的に生成できます。

インストール

  • docker でインストール

  • Docker Hub
    https://hub.docker.com/r/swaggerapi/swagger-ui

Swagger Editor

OpenAPI を記述できるオンラインエディタです。
ブラウザー内で YAML の OpenAPI 仕様を編集し、Swagger UI でドキュメントをリアルタイムでプレビューできます。

画面は、左側にエディター、右側に Swagger UI となっています。

インストール

  • docker でインストール

  • 80番ポートを使用したくない場合 & name 指定

    http://192.168.99.100:8888/

  • Docker Hub
    https://hub.docker.com/r/swaggerapi/swagger-editor

使い方

メニューには大きく、下記があります。

  • File
    インポートやエクスポートが行えます。
  • Edit
    フォーマットのコンバート用のメニューです。
  • Insert
    追加したい項目を入力フォームからエディタに挿入できます。
  • Generate Server
    指定した言語でスタブサーバー用のソースをダウンロードできます。
  • Generate Client
    指定した言語でクライアント用のソースをダウンロードできます。

File、Edit、Insert をさらにみていきます。

File

File メニューをみていきます。

  • Import URL
    OpenAPI に準拠したフォーマットの URL からインポートできます。
  • Import file
    OpenAPI に準拠したファイルからインポートできます。
  • Save as YAML
    YAML ファイルで保存します。
  • Convert and save as JSON
    JSON ファイルにコンバートして保存します。
  • Clear editor
    読み込んでいるエディタをクリアします。
Edit

Edit メニューをみていきます。

  • Convert to YAML
    YAML にコンバートします。
  • Convert to OpenAPI 3
    Swagger 2.0 で記述視されている旧仕様から OpenAPI 3 の仕様にコンバートします。
Insert

Insert メニューをみていきます。

  • Add Path Item
    Path の追加
    summary と description も一緒に追加できます。
  • Add Operation
    Path の Operation を追加
    記述している Path と HTTP メソッドを選択して記述した内容を追加できます。
  • Add Info
    Info の追加
    既に記述している場合は、編集することができます。
  • Add External Documentation
    外部ドキュメントを追加
  • Add Tag Declarations
    タグ宣言を追加
  • Add Tags To Operation
    記述している Path を選択してタグを追加できます。
  • Add Servers
    サーバーを追加

Swagger Codegen

OpenAPI からソースコードを生成するコードジェネレータ
Swagger ドキュメントを解析して、異なる言語でクライアントコードを生成するテンプレート駆動型エンジンです。

YAML ファイル

Swagger のサンプルにある Petstore API を参考に必須部分の YAMLを記述してみます。

  • openapi オブジェクト

  • info オブジェクト

  • paths オブジェクト

エディタで使用

エディタのエクステンションとして使用することができます。

VS Code

VS Code には「OpenAPI (Swagger) Editor」や「Swagger Viewer
」エクステンションがあります。

インストール

EXTENSIONS: MARKETPLACE で「swagger」または「openapi」と入力すると、エクステンションが表示されるので選択してインストールを行います。
OpenApiのjsonを選択すると左に「OpenAPI」アイコンを表示されるので選択すると使えるようになります。「Swagger Viewer」と一緒に使うとWeb版と同様な編集とプレビューが同時にできます。

備考

SwaggerHubは、OpenAPI 仕様をクラウド上で設計、ドキュメント生成できる統合環境で、とても便利です。クラウドでの作業に問題なければこちらのほうがより洗礼されているようですので、おすすめです。
また、Swagger Codegen からフォークした OpenAPI Generator もあるようです。

関連リンク

返信を残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

CAPTCHA