Open API仕様記述ツールを比較してみた

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/321850/52a66db2-2453-7b65-7cfa-64c325fc1b0a.png)


## はじめに

フロントサイドとサーバーサイドのエンジニアが、分業する際に大事なものはなんでしょうか。
コンポーネントの切り方の認識合わせ？？そうかもしれません。
それと同様に大切なのが、**API仕様の共有の仕方**だと思います。
今回、私たちのチームではサーバサイドのAPIの開発に先立ち、フロントサイドの開発をする箇所が出てきたため、
**Open API仕様記述ツール**を投入して仕様共有してみることとしました。


## そもそもOpen API仕様って
**Open API仕様（OpenAPI-Specification）とは、一言で言ってしまえばREST APIを記述する為の仕様。**yamlやjsonに近い形式で記述することができます。
[GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository](https://github.com/OAI/OpenAPI-Specification)


もともと**[Swagger](https://blog.takuros.net/entry/2015/12/02/082248)**っていうフレームワークがあって、USでデファクトスタンダードとなり、のちにその仕様がOpenAPI-Specificationのベースとして採用されたようですね。(2015年)
[![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/321850/7b7737b9-77ec-b2c2-c835-27a799d4bcbf.png)](https://blog.takuros.net/entry/2015/12/02/082248)

[RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに － Publickey](https://www.publickey1.jp/blog/15/open_api_initiative.html)


## Open API仕様/Swaggerの何がいいか
この決められたフォーマットにそって記述することで、

- **コードで管理できる**
- API mockingしたりtestできる
- validateもtypescriptのentityも発行できる
- 言語非依存のmicroservice interfaceとなり、汎用的である  
などなどのメリットが得られるようです。

**wikiなどでのDocument管理は維持管理辛いからもうやめよう。。。。**

## ツール選びで重視するポイント
- **安い**
- チームで共有管理が楽
- サーバー用意してくれてAPI Mockingできると嬉しい
- json schemaを生成してくれる(今回はgraphQLやgRPCなどのツールは対象外)  

## JSON Schema生成ツールでSwagger対抗馬
[JSON Schema 中心設計 - FlowType から RAML まで - - Qiita](https://qiita.com/pika_shi/items/7b8136d5ee3ad8b6957c)
**要はJSON Schemaを、どういうフォーマットのinputで吐き出させるか。**
(**Swagger、Raml、API Blueprint**のフォーマットが一般的)

### 1.Raml
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/321850/820343a6-b661-89e1-a26e-72e3cfd97026.png)

yamlでゴリゴリかく系。
ツールも結構豊富。
Swaggerより読みやすいらしいが、コミュニティの繁栄などもかなり押されている印象
[Swaggerのファイル仕様が不満だったのでRAMLを触って比較してみる - 冥冥乃志](http://mao-instantlife.hatenablog.com/entry/2017/07/01/Swagger%E3%81%AE%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E4%BB%95%E6%A7%98%E3%81%8C%E4%B8%8D%E6%BA%80%E3%81%A0%E3%81%A3%E3%81%9F%E3%81%AE%E3%81%A7RAML%E3%82%92%E8%A7%A6%E3%81%A3%E3%81%A6%E6%AF%94)

**API mockingやtestまで面倒見てくれるSwagger-hub的プラットホームは見つかりませんでした。**

### 2.API Blueprint
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/321850/971e0e11-aaf4-3d91-1a15-edd5939e973b.png)

[apiary.io](https://apiary.io/)というプラットホームが使っているフォーマットが普及した感じらしい。markdown形式で記述できるのが特徴。

>Specを見るとなかなか辛い。
>Modelに名前をつけて使いまわしたり、仕様の記述を複数ファイルに分割する事ができず、時間が経つにつれメンテが困難になっていく。
>JS書く人とサーバAPI書く人が別々で、JS書く人が最初に動き出してうまくAPI仕様も設計できるのなら選択してもよいかも。

([GoConの前哨戦として各種API仕様記述フォーマットについて概要を述べておく - Qiita](https://qiita.com/vvakame/items/c21f7862f6d30a6b2a7b)より引用)

なるほど、**でもmarkdownっぽくかけるのは魅力的。**
#### [apiary.io](https://apiary.io/)
さっきでてきたツール。API mockingまで面倒見てくれる。GitHUb syncでチームで管理できるようです。
Swaggerのフォーマットも選択できるみたいだけど、それならSwagger hubでよくないか感。**しかも 10メンバー99ドルでお安くはない。**
### 3.yamlとか書かないでなんとかしたい(GUI Editor)
**全く中のスキーマ仕様を知らなくてもGUIでぽちぽちできる系**
学習コストが低く、そういう意味でコミュニケーションもフロントとバック間で取りやすそうだ。
フロントサイドもいじることを考えると、理想的っちゃ理想的です。
#### [Apicurio Studio](https://www.apicur.io/)

[OpenAPI-GUI v3.0.0](https://mermade.github.io/openapi-gui/)に近いかな？？
GitHub syncで管理できる。お値段の面でも、**OSSなので無料**なのが素晴らしいです。

**が、しかし**
hubとして使えたりAPImock立てたりtestできるようになる開発は次のフェイズのようです。。
それができれば最強のツールでは？？これからも随時ロードマップを追いかけて、適宜検証していきたい。
[Roadmap \| Apicurio Studio](https://www.apicur.io/roadmap/)

#### [Stoplight](https://stoplight.io/)
APImockも立てれてtestもできる、素晴らしい。
しかし**一人月25ドルかかるので辛い。**

## 暫定結論
ここまで調べて、**だいたいのAPI mockingまでカバーしたプラットホーム系ソフトウェアは高いから一旦諦める**という結論に。（**Swagger-hubも高い(５メンバー月に90ドル)**）


そこで、とりあえずdocker imageやIDEのプラグインなど周辺ツールが優秀なのもあり、**hub以外のSwaggerツール**を使っていくことに。(結局長いものに巻かれた感。必要であれば自社でmockサーバ立ててって感じになるかもしれない。)

[Swagger EditorとSwagger UIとSwaggerのモックAPIサーバーをdocker-compose化してみた - Qiita](https://qiita.com/matsuda_chikara/items/a4119a972535a4b69201)のように、チームでAPI仕様を共有、管理していけるのが理想。

これから運用して、~~辛くなっては他のツールに浮気しながら~~溜まった知見を随時まとめていこうかと思います。

こんなツールがいけてて安いよっていうのがあれば、どんどん教えていただけると大変助かります！よろしくお願いします。
## 参考文献
[GoConの前哨戦として各種API仕様記述フォーマットについて概要を述べておく - Qiita](https://qiita.com/vvakame/items/c21f7862f6d30a6b2a7b)
[API設計ツール「Swagger」が素晴らしい｜萬田大作 / コルクBooks代表｜note](https://note.mu/daisakku/n/n504c1fa7a0e2)
[OpenAPI.Tools](https://openapi.tools/)
[Swaggerとは何か？ - プログラマでありたい](https://blog.takuros.net/entry/2015/12/02/082248)