OpenAPI+RailsでAPIを作ってみた①

はじめに

この記事は今までクライアント側で、「このAPI・・・IF仕様書と実装が違う！」と言っていた新人エンジニアN（以下N）が自分でAPIを作ることになって悪戦苦闘した記録です。

この記事の対象者

インターフェース記述言語(以下IDL)使ってAPIを作ってみたいが何から始めれば良いかわからない・・・というニッチすぎるAPI作成初心者向け。

IF仕様書と実装に差分を出さないためにどうすれば良いか

N：先輩、API作ることになったんでどうやって作るか教えてください。

先輩S(以下S）：おう、ええで。（雑やな

N：今まで疑問だったんですけど、そもそもなんで仕様書と実装に差が出るんですか？

S：よくあるのは開発中に仕様変更があってそれに追従して実装だけしたはいいが、API仕様書の更新を忘れてたってケースやな！

N：ただ忘れてるだけ・・・。

S：あとは単純に開発期間的にドキュメントを更新する時間がなかったってケースもあるわな！

N：ああ・・・、何か仕様書と実装に差をださない方法ってないんですかね？

S：OpenAPIなんかを使って仕様書の作成と実装を連動させればうまくいくと思うで。

N：OpenAPI！なんですかそれ！！

S：OpenAPIはいわゆるインターフェース定義言語(IDL)やで。これはその名前通りインターフェースを定義するための言語や。Open API Initiativeが策定しているREST APIのインターフェース仕様を記述するための仕様のことや。

OpenAPI-Specification
https://github.com/OAI/OpenAPI-Specification

N：けど、これって定義を書くだけでドキュメント化はされないですよね？

S：いや、もちろんドキュメント化もできるで。OpenAPIに従って書くことでサードパーティー製のツールを使って定義からドキュメント、モック、テストなんかも作れるんや。

OpenAPI.Tools
https://openapi.tools/

N：すごいじゃないですか！OpenAPI使ってみたいです！！

S：なら、まずは書いてみよか。OpenAPIはYAMLかJSONで書くことになるんやけど、手書きはしんどいしGUIエディター使うとええで。

N：確かにそっちの方が楽そうですね。どんなエディターがあるんですか？

S：さっき教えたOpenAPI.Toolsに書いてあるほとんどのGUIエディターは有料やけど、今回は手始めに使うんやから無料のApicurio Studioがええで。

N：じゃあそれ使ってみます！

Apicurio Studioのインストール

開発環境

macOS 10.14.6

S：とりあえず構築手順は公式ガイドに書いてある通りや。

N：最新版はv0.2.46.Final（2020/2/27現在)ですね。これってDockerでも構築できるんですね。

S：せやで、まぁ公式ガイドの最初に書いてあるのがJBOSSでローカルサーバを立てる方法やから今回はこっちにしとこか。

N：このコマンド実行するだけですね。


$ mkdir ~/apicurio-studio-0.2.46.Final
$ cd ~/apicurio-studio-0.2.46.Final
$ curl -L https://github.com/Apicurio/apicurio-studio/releases/download/v0.2.46.Final/apicurio-studio-0.2.46.Final-quickstart.zip -o apicurio-studio-0.2.46.Final-quickstart.zip
$ unzip apicurio-studio-0.2.46.Final-quickstart.zip
$ cd apicurio-studio-0.2.46.Final
$ ./bin/standalone.sh -c standalone-apicurio.xml

S：せや、インストールできたらログインしてみよか。