これまで、SmartBear社が提供するSwagger関連ツールを中心に紹介してきました。第一回でも紹介した通り、本家Open API Initiative(OAI)が提供するツールは、以下の表のように他にも多数あります。

表 : OAI公式サイトに掲載のSwaggerツール(赤字)

分類 ツール名
Low-Level tooling swagger-parser, swagger-models, KaiZen OpenAPI Parser, openapi3-ts, swagger2openapi, odata-openapi, microsoft.OpenApi.net, openapi3_parser, oas_parser, oas3-remote-refs, go-openapi, openapi
Editors Apicurio Studio, KaiZen OpenAPI Editor, RepreZen API Studio, OpenAPI-gui, SwaggerHub, swagger-editor
User Interfaces openapi-viewer, swagger-ui, lincoln, WebSphere Liberty, Widdershins, angular-swagger-ui
Code Generators baucis-openapi3, Google Gnostic, Gen, serverless-openapi-documentation, zero-rails_openapi, slush-vertx, WebSphere Liberty, swagger-node-codegen

今回は、こういったツールを掘り下げて紹介していきます。

<Swaggerの基本はこちらで!>

【連載】Swagger入門

Low-Level tooling

Low-Level toolingは呼び名の通り低レイヤの機能を提供しており、言語別に以下の3種類のパターンに大別されます。APIプロバイダから受け取ったSwagger Specファイルを、APIコンシューマ側で読み込み(parse)、クラスやオブジェクト(model)に格納したり、別のバージョンへ変換(conversion)したり、といった使い方になります。

  1. parser:JSONやYAML形式のSwagger SpecファイルをJavaなどのオブジェクトに変換
  2. converter:Swagger Spec 2.0から3.0などバージョン間のコンバージョン
  3. model:Swagger Specの各情報を格納するクラス・オブジェクトを提供する

図 : Swager Specのparseとconversion

上記3つの要素のうち各ツールがどの要素に対応しているかについて下表にて紹介します。

表 : Low-Level toolingの分類

ツール名 言語 parser Model converter
swagger-parser Java
swagger-models Java
KaiZen OpenAPI Parser Java
openapi3-ts TypeScript
swagger2openapi Node.js
Microsoft.OpenApi.net dotnet
odata-openapi XSLT
openapi3_parser Ruby
oas_parser Ruby
oas3-remote-refs Node.js
go-openapi Go
openapi Go

Editors

この分野は文字通りSwagger Specのエディタで、EclipseなどのIDEやブラウザで動作します。

今回は一例として、KaiZen OpenAPI Editor for Eclipseを紹介します。ブラウザで動作するエディタを見たい方は、拙著「Swagger入門」にてSwagger Editorを紹介していますので、ご参照ください。

まずは、インストール作業です。Eclipseの[Help]-[Eclipse Marketplace]から以下の画面にて、[KaiZen OpenAPI Editor]を検索します。[Install]ボタンをクリックします。ライセンスに同意するとインストールが始まります。

図 : KaiZen OpenAPI Editor for Eclipseのインストール

インストールが終わったら、Swagger Specファイルを作ってみましょう。プロジェクトを右クリック[New]-[Other]から以下のウィザードを起動できます。Swagger Spec 2.0、3.0の両方のバージョンを選択できます。

図 : Swagger Specの作成

Swagger SpecファイルがYAML形式で作成されました。

早速エディタの機能を見てみましょう。以下のような一般的なIDEの機能を有しており、開発者の作業の品質や生産性向上に寄与します。

  • エラー表示:シンタックスが誤っている際にエディタ内でエラー表示するとともに、[Problems]ビュー(次画面下部)にてエラー内容を表示
  • アウトライン:ファイルの構成を[Outline]ビュー(次画面右部)にて表示
  • コンテントアシスト:エディタ内にて、適切なシンタックスを提示。画面の例では、[serve]と入力し、[Ctrl]+[Space]をキーストロークすると[servers: array]が候補にある旨提示されています。

図 : KaiZen OpenAPI Editor for EclipseでのSwagger Specファイル編集

User Interfaces

この分野はAPI仕様書の表示機能を提供します。openapi-viewerとwiddershinsを紹介します。

Swagger本家のSwagger UIについては「Swagger入門」をご参照ください。

まずは、openapi-viewerです。以下の通りdockerコマンド1つだけで起動できます。

$docker run -p 8080:8080 koumoul/openapi-viewer
Unable to find image 'koumoul/openapi-viewer:latest' locally
latest: Pulling from koumoul/openapi-viewer
1160f4abea84: Already exists
~中略~
7afbfc9dc918: Pull complete
Digest: sha256:10b5fa66d065cc245b6e6eac4e0325c72f8ef906ba92bff97b67db3aed527200
Status: Downloaded newer image for koumoul/openapi-viewer:latest
Listening on http://localhost:8080

ブラウザから[http://localhost:8080/]にアクセスします。以下の例では[/status]のAPI仕様が表示されています。HTTPレスポンスのステータスコードが200の場合のコンテントタイプなどが表現されています。

図 : openapi-viewerの画面

次にwiddershinsです。前提とする[js-yaml]と[jgexml]をインストールします。公式サイトから[git clone]してから[node]コマンドにて[petstore3.md]ファイルを生成します。

$npm install js-yaml
$npm install jgexml
$git clone https://github.com/Mermade/widdershins.git
$cd widdershins
$node widdershins --search false --language_tabs 'ruby:Ruby' 'python:Python' --summary defs/petstore3.json -o petstore3.md

インプットとして与えたAPI定義であるperstore3.jsonは以下のようなJSON形式で記述されています。

$cat defs/petstore3.json
{
    "openapi": "3.0.0",
    "servers": [
        {
            "url": "http://petstore.swagger.io/v2"
        }
    ],
    "x-origin": [
        {
            "url": "http://petstore.swagger.io/v2/swagger.json",
            "format": "swagger",
            "version": "2.0",
            "converter": {
                "url": "https://github.com/mermade/swagger2openapi",
                "version": "2.6.3"
            }
        }
    ],

~後略~

生成したpertstore3.mdファイルを表示すると以下の通りです。ちなみに、筆者はSublime TextとOmniMarkupPreviewerを使ってmdファイルを表示しています。

図 : API仕様(mdファイル)の表示

Code Generators

この分野はSwagger Specの内容を元にAPIクライアントやサーバのコードを生成するものです。今回は一例として、swagger-node-codegenを紹介します。

Swagger本家のSwagger Codegenについては、「Swagger入門」をご参照ください。

swagge-node-codegenをnpmにてインストールします。次に「User Interfaces」の節で利用したpetstore3.jsonファイルをインプットにNode.jsのサーバのコードを自動生成します。

自動生成されたコードの一つ(store.js)を覗いてみると、Node.jsのWebアプリケーションフレームワーク「Express」をベースにしたソースが生成されていることがわかります。

$npm install -g swagger-node-codegen
$snc petstore3.json -o .
Done!
Check out your shiny new API at /Users/xxxxx/swagger-node-codegen.
$ls src/api/routes/
pet.js      store.js    user.js
$cat src/api/routes/store.js
const express = require('express');
const store = require('../services/store');

const router = new express.Router();

/**
 * Returns a map of status codes to quantities
 */
router.get('/inventory', async (req, res, next) => {
  const options = {
  };
~後略~

Expressなどの依存パッケージをインストールした後、Node.jsサーバを起動します。

$npm install -g express
$npm install -g cookie-parser
$npm install -g body-parser
$npm install -g node-yaml-config
$npm install -g bunyan
$node src/bin/www

ブラウザから[http://localhost:3000/store/order/1]にアクセスします。

図 : Node.jsサーバへアクセス

store.jsの元となったテンプレートを見てみましょう。本家のサイトからクローンします。なお、出力されるソースのテンプレートを変更する場合はsncコマンドにて[-t]オプションを指定します。

$git clone https://github.com/fmvilas/swagger-node-codegen.git
$cat swagger-node-codegen/templates/express-server/src/api/routes/___.js
const express = require('express');
const {{camelCase operation_name}} = require('../services/{{operation_name}}');

const router = new express.Router();

{{#each operation}}
  {{#each this.path}}
    {{#validMethod @key}}
/**
 {{#each ../descriptionLines}}
 * {{{this}}}
 {{/each}}
 */
router.{{@key}}('{{../../subresource}}', async (req, res, next) => {
  const options = {
    {{#if ../requestBody}}
    body: req.body{{#compare (lookup ../parameters 'length') 0 operator = '>' }},{{/compare}}
    {{/if}}
    {{#each ../parameters}}
      {{#equal this.in "query"}}
    {{{quote ../name}}}: req.query['{{../name}}']{{#unless @last}},{{/unless}}
      {{/equal}}
      {{#equal this.in "path"}}
    {{{quote ../name}}}: req.params['{{../name}}']{{#unless @last}},{{/unless}}
      {{/equal}}
      {{#match @../key "(post|put)"}}
        {{#equal ../in "body"}}
    {{{quote ../name}}}: req.body['{{../name}}']{{#unless @last}},{{/unless}}
        {{/equal}}
      {{/match}}
    {{/each}}
  };
~後略~

新しいツールにも注目

今回は、Low-Level tooling、Editors、User Interfaces、Code Generatorsの機能カテゴリごとに、ツールを紹介しました。

Editorsであればブラウザ型やクライアントインストール型があります。Code Generatorsであれば、Node.jsやJava EEやGoなどさまざまな言語に対応しています。

したがって、それぞれのツールの特徴を見極めて取捨選択すると良いでしょう。また、新しいツールが次々と出てきていますので、OAI本家のサイトのツール一覧を適時ご確認ください。

連載を振り返って

前回の連載「Swagger入門」に反響が大きかったため、今回続編を書かせていただきました。APIエコノミーがより広がりを見せ、クラウドやマイクロサービスが進展する状況においては、さまざまなAPIの利用を前提とするため、Swaggerのようなドキュメント化技術の重要性は高まっています。

SwaggerはSwagger Specを中核とし、Swagger UI/Swagger Codegen/Swagger Coreといったツール群で構成されます。もちろん、Swagger単体で開発ができるわけではないので、Apigeeのようなクラウドを前提としたAPI Managementツールを利用したり、CIへ組み込んだりするなど、システム開発全体を見渡して検討する必要があるでしょう。

Swagger Specのバージョンが3.0に上がり、Swagger HubやSwagger Inspectorなど次々と新しいツールが登場してきており、今後もSwaggerの進化から目が離せません。本連載が読者の皆様の技術の引き出しの一つとしてお役に立てれば幸いです。

著者紹介


正野 勇嗣 (SHONO Yuji ) - NTTデータ 課長

2011年まで開発自動化技術のR&Dに従事。その後、開発プロジェクト支援やトラブルシューティング等に主戦場を移す。「ソースコード自動生成」に加えて、JenkinsやMaven等の「ビルド自動化」、JsTestDriverやSelenium等の「テスト自動化」を扱うようになり、多様化する開発自動化技術動向に興味。

最近は第四の自動化であるInfrastructure as Code等の「基盤自動化」の魅力に惹かれている。開発自動化技術に関する雑誌・記事執筆も行う。2児のパパ。