Swaggerの便利ツールまとめ

Swaggerはオープンソース・ソフトウェア、オープンなフォーマットと言うこともあり、関連するライブラリが幾つか存在します。OpenAPI Initiativeが設立されたこともあり、業界標準となっていけばさらに登場してくるのではないでしょうか。

今回はそんなSwaggerによる開発を補助するソフトウェアを紹介します。

Swagger2Markup/swagger2markup

SwaggerファイルをベースにMarkdownファイルを生成するソフトウェアです。若干癖のあるツールですが、MarkdownファイルであればPDFをはじめとして他のドキュメントフォーマットにも展開しやすくなります。

Markdownフォーマットは他の多くのドキュメントシステムでも使われていますので、そういったシステム向けにドキュメントをコンバートする際にも便利です。

BigstickCarpet/swagger-server: Get your REST API up-and-running FAST with Swagger and Express

Swaggerファイルを使ってRESTfulなモックサーバを立てるシステムです。本番環境下ですべてのサービスが揃っていない状態でもクライアント管理がはじめられるようになります。

また、クラウド系サービスにおいてSwaggerファイルを提供することで開発者の環境においてローカルで動作するモックサーバを提供できるようになります。

Swagger UI – Swagger

Swagger UIはSwaggerファイルをHTMLで表示するシステムです。HTML上からCRUD操作を実際に行えるのが特徴です。ただしOAuth2トークンなどが必要であったり、認証などを要する場合は作り込みが発生します。

SwaggerファイルをHTMLとして表示したい時にはこのSwagger UIが最も多く使われるようです。

Swagger Editor – Swagger

Swaggerファイルの作成、編集を行うのがSwagger Editorです。入力内容の検証ツールも組み込まれているので、ミスしたとしても改善しやすいはずです。ツリー構造の折りたたみ機能もあり、大きなAPIドキュメントでも効率的に編集できます。

Swaggerのフォーマットに精通していないと、テキストエディタで書いた後に検証すると多数のエラーが出るはずです。最初からSwagger Editorを使うことで手戻りを減らしましょう。

Swagger Codegen – Swagger

Swaggerでは多数のプログラミング言語に対応したソーコード（スケルトンコード）が生成できます。クライアント/サーバサイドの入力値検証であったり、API利用を簡便化します。

言語によってはソースコードのレベルが高くありませんが、生成されたコードをラッピングして使っても良いでしょう。ドキュメントさえメンテナンスすればライブラリが更新されて最新の状態を保てるというのが理想です。

ReDoc

Swagger UIとは別なドキュメントジェネレータです。データ構造が縦に表示されるのが特徴となっています。今の時点ではSwaggerのファイルを読み込んで動的にコンテンツを生成します。今後の予定としてSEO対策のために静的ファイル生成に対応するようです。

画面構成は3ペインで、一番右側にコードサンプルが表示できます。

moongift/cURLtoSwagger: Convert from cURL command to YAML format. Compatible with Swagger.

筆者が作っているツールがcURLtoSwaggerです。cURLコマンドとそのレスポンスを使ってSwagger用のドキュメントを生成します。cURLコマンドはGoogle Chromeの開発者ツールで取得できます。

Swaggerはサービス提供側が記述する場合もあれば、すでにできあがっているAPIからドキュメントだけ書き起こす場合もあるでしょう。cURLtoSwaggerは後者向けのツールになります。

Swagger（OpenAPI Specification）に関連したツールは今後増えていくと予想されます。そうすることでSwaggerのエコシステムはさらに広がっていくことでしょう。API/ドキュメントファーストの開発においてSwaggerは見逃せない存在になるはずです。