![見出し画像](https://assets.st-note.com/production/uploads/images/78720537/rectangle_large_type_2_19377673a369bc9265f1044e0645749a.png?width=1200)
Stoplight Studioを使ってREST APIのスキーマ駆動開発に対するハードルを下げる
こんにちは、みみぞうです。
ナビタイムジャパンで『システムや開発環境、チームの改善』を担当しています。
今回はStoplight Studioを使って、OpenAPI Specificationを使ったスキーマ駆動開発のハードルを下げる方法を紹介します。
📝はじめに
本稿は以下の方をターゲットにしています。
REST APIを開発する方
REST APIを利用して開発する方
特に、『OpenAPI SpecificationのYAMLファイルを編集するのが大変』と感じている方にお勧めです。
📚各用語の説明
本稿で登場する各用語の説明をします。
OpenAPI Specificationとは
OpenAPI Specificationとは、言語に依存しないREST APIの標準インターフェース仕様です。以降ではOASと略します。
OASの最新バージョンはv3であるため、本稿ではv3を対象とします。
OpenAPIドキュメントとは
OASの仕様に沿って作成されたファイルをOpenAPIドキュメントと呼びます。フォーマットはYAMLとJSONの両方に対応しています。
以下は /ping というAPIの仕様を記述したOpenAPIドキュメントの例です。
openapi: "3.0.0"
info:
version: 1.0.0
title: サンプル
servers:
- url: http://localhost
paths:
/ping:
get:
responses:
'200':
description: "OK"
content:
application/json:
schema:
$ref: '#/components/schemas/Ping'
components:
schemas:
Ping:
type: object
required:
- ping
properties:
pong:
type: boolean
レスポンスの形式は以下を想定しています。
{
"pong": true
}
スキーマ駆動開発とは
本稿では、スキーマ駆動開発を『OpenAPIドキュメントを起点とした開発』と定義します。
OpenAPIドキュメントは提供されている各ツールを使うことで、様々なモノを生成できます。
![](https://assets.st-note.com/img/1652752534717-emyq7IBkbp.jpg?width=1200)
この恩恵を最大限に受けるため、スキーマ駆動開発では以下の手順を踏みます。
1から必要なモノを自動生成
API開発者、APIを利用する開発者が必要なモノを更新
😟スキーマ駆動開発のハードル
OpenAPIドキュメントさえしっかりメンテナンスできれば、非常に合理的なスキーマ駆動開発ですが、大きなハードルがあります。それは、熟練者でないとOpenAPIドキュメントの編集は難しいということです。
たとえば、GET /users/{userId} と POST /user の2つを含むOpenAPIドキュメントは以下のようになります。(内容の理解は不要です。雰囲気だけ感じとってください)
openapi: 3.1.0
info:
title: note執筆用サンプルAPI
description: note執筆用に作成したサンプルAPI
version: '1.0'
contact:
name: みみぞう
servers:
- url: 'http://localhost:3000'
tags:
- name: ユーザー
paths:
'/users/{userId}':
parameters:
- schema:
type: integer
name: userId
in: path
required: true
description: ユーザーID
get:
summary: ユーザーIDからユーザーを取得
description: ユーザーIDに一致するユーザー情報を取得します
operationId: get-users-userId
tags:
- ユーザー
responses:
'200':
description: ユーザー取得に成功
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
ユーザーAを取得:
value:
id: 1
name: ユーザーA
dateOfBirth: '2000-01-01'
createdDate: '2019-08-24'
'404':
description: ユーザーが見つかりません
/user:
post:
summary: 新しいユーザーの作成
description: 新しいユーザー情報を作成します
operationId: post-user
tags:
- ユーザー
responses:
'200':
description: ユーザー作成に成功
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
ユーザーBを作成:
value:
id: 2
name: ユーザーB
dateOfBirth: '2001-01-01'
createdDate: '2020-11-18'
'400':
description: 必須の情報が不足しています
requestBody:
description: 登録するユーザー情報
content:
application/json:
schema:
type: object
properties:
name:
type: string
dateOfBirth:
type: string
format: date
required:
- name
examples:
Create ユーザーB:
value:
name: ユーザーB
dateOfBirth: '2001-01-01'
components:
schemas:
User:
title: ユーザー
type: object
description: ''
examples:
- id: 1
name: ユーザーA
dateOfBirth: '2000-01-01'
createdDate: '2019-08-24'
properties:
id:
type: integer
description: ユーザーごとにユニークなID
name:
type: string
dateOfBirth:
type: string
format: date
example: '1997-10-31'
createdDate:
type: string
format: date
description: ユーザーが作成された日時
required:
- id
- name
- createdDate
Swagger Editorを使えば、補完やプレビュー・エラー表示も可能になり、かなり編集しやすくなります。
それでも、YAMLを直接編集しなければいけないため、OASを知り尽くしていなければ難易度は高いでしょう。私もそれなりにOpenAPIドキュメントを作成してきましたが、どこに何を書けばいいか、未だに迷うことが多いです。
✨Stoplight Studioでハードルを下げる
この問題をStoplight Studioが解決してくれます。
Stoplight Studioとは
Stoplight StudioはOASに沿ったAPIをデザインするため、様々な機能を提供するGUIツールです。
GitHubのリリースページからインストールできます。(公式サイトにはWeb版もあります)
Stoplight Studioの特徴
Stoplight Studioには主に以下のメリットがあります。
GUIでOpenAPIドキュメントを簡単に編集できる
YAML編集で補完やエラーチェックができる
API仕様書をプレビュー表示できる
モックサーバーが使用できる
APIへリクエストして結果を確認できる
1つずつ詳細を見ていきましょう。
GUIでOpenAPIドキュメントを簡単に編集できる
YAMLではなくGUIから直感的にOpenAPIドキュメントを編集できます。先ほど紹介したYAMLの場合、Stoplight Studioでは以下のように表示されます。
![](https://assets.st-note.com/img/1652752738975-yoPDNbz6Mj.png?width=1200)
参照だけでも見やすいですが、嬉しいことに画面上の項目をそのまま編集できます。components配下のようなパーツも、左サイドメニューにまとまっており非常に管理しやすいです。
![](https://assets.st-note.com/img/1652752777684-GO3piApuTK.png?width=1200)
また、Generate from JSONボタンをクリックすると、JSON形式のレスポンスから自動でスキーマを推定します。
![](https://assets.st-note.com/img/1652752793090-a2toQhnZy1.png)
入力してGenerateボタンを押すと、推定した結果で更新されます。
![](https://assets.st-note.com/img/1652752806157-Vv05zesFk7.png?width=1200)
YAML編集で補完やエラーチェックができる
Swagger Editorと同様にYAMLの編集もできます。細かな調整をしたいとき、YAML編集の方が早い場合は使い分けられます。
![](https://assets.st-note.com/img/1652752815377-XaGNq27mru.png?width=1200)
補完もばっちりです。
![](https://assets.st-note.com/img/1652752824265-zkpnZ88jVJ.png)
エラーや警告も表示されます。
![](https://assets.st-note.com/img/1652752829677-ixvH0s3rf3.png?width=1200)
API仕様書をプレビュー表示できる
OASのツールにはSwagger UIと呼ばれるデプロイ用のUIが提供されています。
🌎REST API Documentation Tool | Swagger UI https://swagger.io/tools/swagger-ui/
Swagger UIとはデザインが異なりますが、Stoplight Studioでも仕様書のプレビュー表示ができます。先ほどの画面は編集用のUIでしたが、こちらは閲覧用です。
![](https://assets.st-note.com/img/1652752903790-HM6wM7s4AA.png?width=1200)
モックサーバーを使用できる
実際にAPIのプログラムを書かなくても、モックサーバーを使用できます。モックサーバーはOpenAPIドキュメントの仕様を満たすようなダミーデータを返却します。
![](https://assets.st-note.com/img/1652752916304-WnELPPLq1O.png?width=1200)
APIごとにMockサーバーのURLが書いてあります。アクセスするとランダムのダミーデータが入ったレスポンスを取得できます。
![](https://assets.st-note.com/img/1652752925613-Lq6ExUdlvt.png?width=1200)
モックサーバーを使うことで、APIの実装を待たずにAPIを呼び出すプログラムの開発ができます。
APIへリクエストして結果を確認できる
Swagger UIでは任意のリクエストを作成し、結果を確認できます。Stoplight StudioのTry Itタブでも同じことができます。
![](https://assets.st-note.com/img/1652752943967-7HmwRwI6C6.png?width=1200)
エンドポイントには、先ほどのモックサーバーを選ぶこともできます。
![](https://assets.st-note.com/img/1652752951557-E2xDqyHlO7.png)
また、各言語ごとのサンプルコードも併せて表示できます。
![](https://assets.st-note.com/img/1652752957902-SXnEluMamQ.png?width=1200)
📜まとめ
REST APIのスキーマ駆動開発をするにあたり、『OpenAPIドキュメントのYAMLファイルを編集するのが大変』という問題を解決するため、Stoplight Studioを紹介しました。
OpenAPIドキュメントの編集だけでなく、API仕様書のプレビュー、REST APIクライアント、モックサーバーとしての機能もあり、APIを利用する開発者にも便利です。
現代では、ほとんどの開発がREST APIに関係すると思いますので、よろしければお試しください。