OpenAPI関連のサイト・ツールまとめ
2020.10.29
OpenAPI関連のサイトやツールなどの情報が種々雑多にあるので、自分の中での整理と忘備録として残すためにまとめました。（2020年10月時点）
目次
概要
OpenAPIとは
OpenAPIという表現が使われた場合、恐らくそれらの多くはOpenAPI Specification（以下OAS）に基づいてJSONやYAMLで記述されたREST APIの仕様書（スキーマ）を指しているように思います。
OASはREST APIの仕様を記述するための規格であり、それ自体がなにかのツールやサービスを提供するものではありません。
とはいえ関連するツールやサービスも普及してきているので、あまり言葉の意味を気にしすぎる必要もないかもしれませんが。
- OpenAPI Specification (v3.0.3)
- Implementer’s Draft (OAS 3.1 RC1) Available for Feedback – Please Respond by Nov 8!
現在の最新バージョンは 3.0.3 、次のバージョンとなる 3.1.0 はもうすぐリリースされそうな様子です。
OASはOpenAPI Initiativeによって規格化が推進されています。
The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how APIs are described. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor neutral description format. The OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software.
https://www.openapis.org/about
Swaggerとの関係
OpenAPIと同じような文脈でSwaggerというキーワードも使われていますが、これは全く関係のない別物というわけではありません。
ひとつはSwagger Specificationとして知られていた規格ですが、これらはOpenAPI Specificationとして名前が変わりました。
一般的にSwaggerのスキーマと書かれていたらOASのv2.0のスキーマと読みかえてよいかと思います。（v1.2については使ったことがないのとほぼ見かけないので）
v2とv3は構造など一部仕様変更があり、ライブラリやツールによってはv3に対応していないなど少し状況が変わるので適宜選択するとよいでしょう。
v2とv3は相互に変換するツールなどもあるため後から変えたいというのも難しくはないと思いますが、現状制約がなければv3を使っておけばよいと考えています。
This repository also contains the OpenAPI Specification 2.0, which is identical to the Swagger 2.0 specification before it was renamed to “OpenAPI Specification”, as well as the Swagger 1.2 and Swagger 2.0 specifications.
https://github.com/OAI/OpenAPI-Specification#previous-versions
またウェブサイトを見るとSwagger自体は「OpenAPI Specificationに関する作業を補助するためのオープンソースのツール群」であると書かれていました。
Swagger UIはOpenAPIのスキーマを書いたことがあれば一度は目にしたことがあるのではないでしょうか。
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.
https://swagger.io/docs/specification/about/
これについても大体はSwagger＝Swagger（OAS v2.0）のスキーマぐらいの意味で使われていることが多いように思います。
OAS関連のツール・サービス
前述の通りOASは規格であり、公式のツールやサービスというものはないと考えています。
Swaggerについては経緯からすると微妙なラインかもしれませんが、一応OASに準拠したツールを提供しているものと捉えています。
ちなみにOASのリポジトリにImplimentationsというページがあるものの、積極的に更新されているのか微妙なところです。
掲載の基準などがあるのかもしれませんが、ここにあるものは一部と捉えてもよさそうです。
また、ここへの掲載自体が特定のツールを支持するものではないとも書かれています。
その他に以下のようなOAS関連のツールをまとめたページがありました。
これら全てのツールを紹介することはできないので、今まで使ったことがあるものや気になっているものなどに絞って可能なかぎり紹介していきます。
Swagger
なにはともあれOASについて調べればSwaggerを目にしないことはないでしょう。
オープンソースのツール郡
Swaggerは以下のオープンソースのツールを提供しています。
Swagger Editorはブラウザ上でOASのスキーマを編集しながらプレビューが可能なエディタで、バリデーションもしてくれるので記述がおかしい場合などにすぐ気づくことができて便利です。
デモサイトで試すことができます。
Swagger UIはOASのスキーマを人間が読みやすいようなUIで表現してくれます。（Swagger Editiorのプレビューはこれと同じです）
JSONやYAMLで書いたスキーマを読んでくれと言われても困るので、レビューの際やドキュメントとして管理するのに便利です。
Swagger CodegenはOASに基づいたサーバースタブ、APIクライアントを生成することができます。
これについては後述するOpenAPI Generatorと合わせて詳しく紹介します。
これらのツールはDockerでも簡単に使うことができます。
- Docker Hub: swaggerapi
SwaggerHub
SwaggerはSwaggerHubというSaaSを提供しており、チームでAPIデザインを促進するためのプラットフォームとしています。
ごく簡単に言えばSwagger EditorとSwagger UIのホスティングサービスのようなものです。
SwaggerHubを使えばチームでスキーマを編集したり、シェアしたりするといった作業が簡単にできます。
Swagger EditorやSwagger UIは便利ですが、チームの規模が大きくなったりプロジェクトの数が増えると運用コストもかかってくるのでそのあたりにお困りの場合は検討してみてはいかがでしょうか。
Freeプランではパブリックなプロジェクトしか作成できないのですが、外部向けのAPI仕様を公開するような場合などは十分に使えるかと思います。
内部的なAPI仕様などプライベートなプロジェクトを作成するためには有料プランに契約する必要があります。
また、SwagggerHub上に展開したスキーマは自動的にモックサーバーが割り当てられます。
バックエンドとフロントエンドの開発が切り分けられている場合、スキーマだけ用意すれば追加の手順などなくモックサーバーでフロントエンドの開発を進めることができるのでとてもありがたい機能ではないでしょうか。
ただしRate Limitは “10 requests per minute per API version” となっているので、本格的に使うには厳しいかもしれません。
- SwaggerHub: API Auto Mocking
Stoplight
Stoplightは最近OAS関連の記事でよく見かけるのですが、かなり評判が良いように見受けられます。
ポジション的にはSwaggerとほぼ同じで、OAS関連のツールをオープンソースで提供しつつSaaSとしても様々な機能を提供しています。
Studio
StudioはOASのスキーマのエディタです。
Swagger Editorに比べるとGUIで編集できるのが大きな利点だと考えています。
Swagger EditorはあくまでもJSONやYAMLを書くための補助なので、補完などはあるものの基本的に書き方を知っている前提となります。
StudioはGUIで編集できるのでOASの細かい書き方を知らなくても、API設計についての基本的な知識があれば編集できるようなUIになっています。（OASについて知る必要がなくなるものではないですが）
もう一つ大きな利点として、エンドポイントが多くなり行数が増えたJSONやYAMLを部分的に編集するのは大変になってきますが、StudioならGUIで必要な箇所にパスなりパラメータをポチっと追加すればいいので編集が容易であることも大きいと思います。
YAMLの差分をコードとして見やすいようにしたい場合はこちらの記事もおすすめです。
Studioではボタンひとつでモックサーバーを起動することができます。
モックサーバーは後述のPrismを使っているようですが、みたところStudioではPrismのポート番号などのオプションを変更することができなさそうなのでオプションを変更したい場合はPrismを直接使うことになりそうです。
- Stoplight Studio: Mock Servers
Prism
PrismはOASのスキーマを元に動作するモックサーバーを起動するツールです。
Studioを使っていてオプションを変更する必要がなければ直接使う必要はなさそうですが、Studioを使うことが前提でない場合などもPrismを使うと良いかと思います。
Prismに関しては以下の記事で試した内容を書いているのであわせてご覧ください。
Spectral
SpectralはOASのスキーマのLinterです。
他にもOASのスキーマをチェックしてくれるツールはあり、後述するOpenAPI Generatorの validate コマンドを使ったりしていたのですが、SpectralはルールをカスタムできることとVS Codeの拡張機能が提供されていることなどが決め手でこちらに乗り換えました。
特にVS Codeの拡張機能は過去の記事でも紹介しているような $ref によるファイル参照を使ったスキーマでも問題なく機能するのが嬉しいポイントです。
Stoplight Platform
Stoplight PlatformはSwaggerにおけるSwaggerHubのようなサービスです。
Stoplight Platformではチームでスキーマを編集したりドキュメントを管理したりすることができます。
ドキュメントとしての体裁はSwagger UIに近い感じですが、OASのスキーマとは別にMarkdownで記述ができたりするようです。
また、Freeプランでもプライベートなプロジェクトが作れるようです。
cliも提供されているので、CIで特定のリポジトリ、ブランチの情報に更新することもできそうです。
SwaggerHubにかなり近い印象ですが、無料でプライベートなプロジェクトも作れるのでとりあえずひとつ何かのプロジェクトで運用してみたいというにはこちらがいいかもしれません。
OpenAPI Generator
OpenAPI GeneratorはOASに基づいたサーバースタブ、APIクライアントを生成することができます。
これだけみるとSwagger Codegenと同じでは、と思ってしまうのですが何が違ってどちらを選べばよいのでしょうか。
以下の記事によるともともとSwagger Codegenを開発していた一部のメンバーがフォークしたプロジェクトをコミュニティドリブンで開発しているそうです。
そのためSwagger CodegenとOpenAPI Generatorはツールとしては同じ部類になるものの、開発の状況や方針などが異なるのでどちらを選ぶかはユーザー次第ということになります。
自分はAPIクライアントのコードを生成して利用する部分はあまり触れていないのですが、OpenAPI Generatorのほうが対応する言語が多く開発も活発という意見が多いように見受けられました。
以下の記事でSwagger CodegenとOpenAPI Generatorが対応している言語を比較した情報がまとまっているので、どちらも対応している場合は生成されたコードを見比べたうえで判断してもいいかもしれません。
あまり違いを意識せずに使っていたのであらためて考える機会になりました。
- Rhyztech blog: Swagger Codegen と OpenAPI generatorの比較(2020/02版)
自分は分割したYAMLのスキーマをひとつのJSONのスキーマに結合したり、Markdownのドキュメントを生成するのにも利用しています。
クライアントサイドの利用については以下の記事もあわせてご覧ください。
サーバースタブ
サーバースタブはあまり活用できていないのですが、APIクライアントと同様で生成は簡単です。
サーバースタブという言葉自体はモックサーバーと同様にAPIサーバーをテスト段階で置き換えるものというニュアンスだと思っていましたが、Swaggerのドキュメントにはロジックを実装してデプロイするベースにしてもよいと書いてありました。
（server stubを元に表記していますが日本語ではスタブサーバという表記が多いようです）
With SwaggerHub, you can easily generate a server stub (an API implementation stub) for Node.js, ASP.NET, JAX-RS, and other servers and frameworks. The server stub is a good starting point for implementing your API – you can run and test it locally, implement the business logic for your API, and then deploy it to your server.
https://app.swaggerhub.com/help/apis/generating-code/server-stub
ロジックを実装までしないにしても前述のPrismのようなモックだとレスポンスの内容を細かく制御できないのでつらい、というような場合はサーバースタブでレスポンスのデータを都合に合わせて細かく制御することで対応できるかもしれません。
サーバースタブを使うにはモックサーバーより一手間かかりますが、状況に応じて使い分けるとよさそうです。
サーバースタブも種類があるのですがJavaScriptであれば nodejs-express-server などが利用可能です。
サーバーサイドにおけるOASの活用
ここまでに紹介したツールはOASの設計、クライアントサイドの開発支援が主な目的でした。
では実際にAPIを実装するサーバーサイドからはどう活用することができるでしょうか？
せっかくOASのスキーマに従ってフロントエンドの実装が進んだのに、サーバーサイドが実装したAPIの返すデータが違っては意味がありません。
そのような問題が起きないようにするためにはサーバーサイドもOASのスキーマに従ったAPIの実装をすべきで、さらにはそれが保証される仕組みがあるとよいと考えています。
スキーマに従った開発といってもアプローチは無数にあるので全てを紹介することはできませんが、弊社の取り組みを一例として紹介します。
Ruby on Rails
弊社ではAPIサーバー実装の際、Ruby on Rails（以下Rails）を主な選択肢のひとつとしています。
OASのスキーマからRubyのコードを生成したり、Railsのコード内にOASの定義を記述して生成するライブラリなどもあるのですが、OASの新しいバージョンへの対応状況がまちまちだったり他のライブラリへの依存が発生したりするのでいまのところ利用していません。
基本的にはOASのスキーマを書き、それに従うように実装するということだけをしています。
RailsでOASのスキーマに従ったレスポンスを返しているかどうかを検証するのにcommittee-railsを使った、という記事を書いているのであわせてご覧ください。
現状これで完璧な状態とは言い切れませんが、いまのところはAPIのレスポンスがOASのスキーマに従っているということをテストで検証できているのでよしとしています。
Laravel (PHP)
Rails以外にもLaravelでのAPI開発もしているのですが、以下のライブラリで同様のテストをしています。
OAS以外の選択肢
REST APIを設計する場合にはOASが唯一の選択肢というわけではなく、比較対象としてよく見かけるのがRAML、API Blueprintなどです。
相互に変換するツールもあるので、OASで書いたスキーマが他ではどうなるか比較してみても面白いかもしれません。
RAML
RAMLはRESTful API Modeling Languageの略でその名の通りREST APIを設計するための言語です。
YAMLで記述されたRAMLの定義は一見するとOASにも近いような印象があります。
APIの設計やドキュメントの生成と共有、さらにはコードの自動生成などが可能でエコシステムとしてもOASに近いものがあるように思いました。
ちなみにRAMLの開発の中心的な存在であるMuleSoftはOpenAPI Initiativeに参加しており、RAMLはOASと対立するものではなく同じエコシステムのなかで共存するものという見解のようです。
導入事例がないわけではないのですが、OASに比べると少し印象が薄いかなと思いました。
API Blueprint
API BlueprintはApiaryがオープンソースとして開発しているAPI仕様を記述する言語です。
API BlueprintはOASやRAMLと比べるとMarkdownで記述するのが特徴的でしょうか。
慣れの問題かもしれませんが、個人的にはOASをYAMLで書くのが一番簡単かなと思いました
周辺のツールなども多く提供されているのでAPIの設計やドキュメント化、開発への導入なども十分できそうです。
ただしAPI Blueprintの定義ファイルをインポートできるツールやサービスは多くなさそうなので、ApiaryとAPI Blueprintで全てまかなうと考えれば選択肢になるかもしれません。
ちなみにApiaryのSaaSではAPI Blueprintだけでなく、OASの定義ファイルの編集やドキュメントとしてのホスティングが可能です。
UI上はSwaggerとなっていますがOASのv3.0にも対応しており、Swagger UIとは異なりますがプレビューやモックサーバーへのリクエストも可能です。
まとめ
OASの概要とごく一部ですが周辺のツールの紹介をしました。内容に関しては思いついたときに更新、追記していこうかと思っています。
個人的にはStoplightのツールがよさそうだなと思っているので動向を追っていきたいです。
OASはREST APIの仕様を記述しドキュメント化するというだけのものではなく、エコシステムから生まれる周辺ツールを利用できることも大きな魅力です。
もちろんスキーマファーストという観点ではGraphQLなどその他の選択肢もあるので、OASにこだわらず比較検討はしてみるべきだと思います。
既存のREST APIのコードがある場合は、ただ見せるためだけのドキュメントを書くのではなくOASのスキーマを定義することでドキュメントの生成とREST APIのテストへの活用など段階的に導入していくこともできるのではないでしょうか。
事例が多いというのは十分導入を後押しするものだと思いますが、しばらくOASに触れてきた今改めてRAMLやAPI Blueprintにも目を向けてみようと思いました。
