はじめに

この記事は今までクライアント側で、「この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:せや、インストールできたらログインしてみよか。

Apicurio studioにログイン

外部サーバーに構築したり、複数人での作業することを想定して作られているためApicurio Studioを使うためにはログインする必要があります。

S:インストールが終わったらログインしてみよか。

https://localhost:8443/studio/

N:あ、ログインが必要なんですね。

S:せやで、外部サーバーに立てて複数人で作業することも考えられて作られてるからログインが必要なんや。

N:ログイン画面が表示できました。

S:ほな、Registerからユーザー登録しようか

N:名前とかのユーザー情報は適当でいいんですか?

S:所詮ローカルにお試しで立ててる環境やから問題ないで。

N:(なら、適当に先輩の名前でいいや
  ・・・できました!

S:俺の名前かい!まぁええわ、次から実際にOpenAPIに則ってAPI定義を書いていこか。


次回から実際Apicurio Studioを使ってインターフェース仕様を定義していきます。


Facebook Comments