OpenAPI の定義を Stoplight Studio で書く

こんにちは、 Gaji-Labo アシスタントエンジニアの石垣です。

今回は OpenAPI の定義ファイルを Stoplight Studio で書く機会があったため、自身の理解を深めるためにも OpenAPI と Stoplight Studio についてまとめてみます。

OpenAPIとは？

OpenAPI は、REST APIの定義を記述するためのフォーマットである「OpenAPI Specification」の略称です。元々「Swagger」という REST API を設計、構築、文書化、および使用などを行うためのフレームワークが存在し、そこで用いられていたフォーマットが標準化されたものが OpenAPI のようです。

スキーマ駆動開発で分離されているバックエンドとフロントエンドの実装を繋ぎこむために OpenAPI が用いられます。

OpenAPI の定義は JSON や YAML 形式で記述されますが、ツールを使うことで直接 JSON などを書くことなく記述することが可能です。

今回は Stoplight Studio というツールを使って OpenAPI を書いてみます。

Stoplight Studio を使用する

Stoplight Studio は OpenAPI 定義ファイルの作成と管理のためのツールです。

公式サイトからダウンロードし、起動するとプロジェクトの選択画面が表示されます。

今回は新規プロジェクト上で API を定義し、エンドポイントにアクセスすると値が返ってくるサンプルを作成してみます。

OpenAPI で定義できる API やモデル、エンドポイントは、Stoplight Studio では左上のメニューから作成することができます。

まずは API 本体を作成します。作成するとサンプルのモデルが追加されます。

次にモデルを作成します。API の中にモデルを作成するには、API内のModel を右クリックして New Model を選択します。

モデルのスキーマでそのモデルが返す値を定義します。今回は Example という名前で以下のような値を定義しました。

次にエンドポイントを作成します。今回は example/ で作成しました。

エンドポイント側が 200 応答した時に値が返るようにするため、Schema の TYPE に先程作成したモデルを指定します。

エンドポイントを作成すると、Mock Server でAPIの確認をすることが可能になります。右上のMocks を選択し、先程作成した example/ を見てみます。

エンドポイントにアクセスすると、先程定義した値が Mock で返されているのが分かります。

これで一連の定義を行うことが出来ました。

右上のメニューからコードを見ると、実際の定義ファイルが作成されているのが分かります。

まとめ

今回は Stoplight Studio で OpenAPI の定義を書く方法についてまとめました。

まだ OpenAPI に関しては勉強途中のため、今後も仕様・書き方の双方を学んでいきたいと思っています。よろしくお願いします！