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公式サイトのキャプチャ

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

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

起動すると新規プロジェクトの作成・存在しているGitリポジトリからのプロジェクト作成・既存ディレクトリからのプロジェクト作成の選択画面が表示される

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

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

Stoplight Studio の左上のメニューのキャプチャ

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

example という名前の API を作成

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

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

Example という名前のモデルを作成し、スキーマを定義

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

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

エンドポイント側で Response 200 に先程作成したモデルを指定

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

エンドポイントを作成すると自動で Mocks に追加される

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

定義した値が Mock で返されているブラウザ表示のキャプチャ

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

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

出力された、作成したモデルの実際のコード

まとめ

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

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

Gaji-Laboでは、React経験が豊富なフロントエンドエンジニアを募集しています

弊社ではReactの知見で事業作りに貢献したいフロントエンドエンジニアを募集しています。大きな制作会社や事業会社とはひと味もふた味も違うGaji-Laboを味わいに来ませんか?

もちろん、一緒にお仕事をしてくださるパートナーさんも随時募集中です。まずはお気軽に声をかけてください。お仕事お問い合わせや採用への応募、共に大歓迎です!

求人応募してみる!

投稿者 Ishigaki Shotaro

アシスタントエンジニアとしてHTML/CSS/JavaScriptの実装やRailsの組み込み、スタイルガイドの構築などを担当しています。 業務の中でさまざまな学びを吸収しながら、文書構造やアクセシビリティに目を向けたマークアップの学習やJavaScriptの学習などを行っています。チームに貢献できるエンジニアとなるために日々奮闘中です。