Help us understand the problem. What is going on with this article?

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

More than 1 year has passed since last update.

image.png

はじめに

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

そもそもOpen API仕様って

Open API仕様(OpenAPI-Specification)とは、一言で言ってしまえばREST APIを記述する為の仕様。yamlやjsonに近い形式で記述することができます。
GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository

もともとSwaggerっていうフレームワークがあって、USでデファクトスタンダードとなり、のちにその仕様がOpenAPI-Specificationのベースとして採用されたようですね。(2015年)
image.png

RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに - Publickey

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
要はJSON Schemaを、どういうフォーマットのinputで吐き出させるか。
(Swagger、Raml、API Blueprintのフォーマットが一般的)

1.Raml

image.png

yamlでゴリゴリかく系。
ツールも結構豊富。
Swaggerより読みやすいらしいが、コミュニティの繁栄などもかなり押されている印象
Swaggerのファイル仕様が不満だったのでRAMLを触って比較してみる - 冥冥乃志

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

2.API Blueprint

image.png

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

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

(GoConの前哨戦として各種API仕様記述フォーマットについて概要を述べておく - Qiitaより引用)

なるほど、でもmarkdownっぽくかけるのは魅力的。

apiary.io

さっきでてきたツール。API mockingまで面倒見てくれる。GitHUb syncでチームで管理できるようです。
Swaggerのフォーマットも選択できるみたいだけど、それならSwagger hubでよくないか感。しかも 10メンバー99ドルでお安くはない。

3.yamlとか書かないでなんとかしたい(GUI Editor)

全く中のスキーマ仕様を知らなくてもGUIでぽちぽちできる系
学習コストが低く、そういう意味でコミュニケーションもフロントとバック間で取りやすそうだ。
フロントサイドもいじることを考えると、理想的っちゃ理想的です。

Apicurio Studio

OpenAPI-GUI v3.0.0に近いかな??
GitHub syncで管理できる。お値段の面でも、OSSなので無料なのが素晴らしいです。

が、しかし
hubとして使えたりAPImock立てたりtestできるようになる開発は次のフェイズのようです。。
それができれば最強のツールでは??これからも随時ロードマップを追いかけて、適宜検証していきたい。
Roadmap | Apicurio Studio

Stoplight

APImockも立てれてtestもできる、素晴らしい。
しかし一人月25ドルかかるので辛い。

暫定結論

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

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

Swagger EditorとSwagger UIとSwaggerのモックAPIサーバーをdocker-compose化してみた - Qiitaのように、チームでAPI仕様を共有、管理していけるのが理想。

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

こんなツールがいけてて安いよっていうのがあれば、どんどん教えていただけると大変助かります!よろしくお願いします。

参考文献

GoConの前哨戦として各種API仕様記述フォーマットについて概要を述べておく - Qiita
API設計ツール「Swagger」が素晴らしい|萬田大作 / コルクBooks代表|note
OpenAPI.Tools
Swaggerとは何か? - プログラマでありたい

fukubaka0825
Site Reliability Engineer at eureka, Inc. devops/AWS/IaC/Terraform/コンテナ/サーバレス/Go/DDD
https://www.fukubaka0825.dev/
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした