見出し画像

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ドキュメントは提供されている各ツールを使うことで、様々なモノを生成できます。

この恩恵を最大限に受けるため、スキーマ駆動開発では以下の手順を踏みます。

  1. OpenAPIドキュメントを更新

  2. 1から必要なモノを自動生成

  3. 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 StudioOASに沿ったAPIをデザインするため、様々な機能を提供するGUIツールです。

GitHubのリリースページからインストールできます。(公式サイトにはWeb版もあります)

Stoplight Studioの特徴

Stoplight Studioには主に以下のメリットがあります。

  • GUIでOpenAPIドキュメントを簡単に編集できる

  • YAML編集で補完やエラーチェックができる

  • API仕様書をプレビュー表示できる

  • モックサーバーが使用できる

  • APIへリクエストして結果を確認できる

1つずつ詳細を見ていきましょう。

GUIでOpenAPIドキュメントを簡単に編集できる

YAMLではなくGUIから直感的にOpenAPIドキュメントを編集できます。先ほど紹介したYAMLの場合、Stoplight Studioでは以下のように表示されます。

参照だけでも見やすいですが、嬉しいことに画面上の項目をそのまま編集できます。components配下のようなパーツも、左サイドメニューにまとまっており非常に管理しやすいです。

また、Generate from JSONボタンをクリックすると、JSON形式のレスポンスから自動でスキーマを推定します。

入力してGenerateボタンを押すと、推定した結果で更新されます。


YAML編集で補完やエラーチェックができる

Swagger Editorと同様にYAMLの編集もできます。細かな調整をしたいとき、YAML編集の方が早い場合は使い分けられます。

補完もばっちりです。

エラーや警告も表示されます。


API仕様書をプレビュー表示できる

OASのツールにはSwagger UIと呼ばれるデプロイ用のUIが提供されています。

🌎REST API Documentation Tool | Swagger UI https://swagger.io/tools/swagger-ui/

Swagger UIとはデザインが異なりますが、Stoplight Studioでも仕様書のプレビュー表示ができます。先ほどの画面は編集用のUIでしたが、こちらは閲覧用です。

モックサーバーを使用できる

実際にAPIのプログラムを書かなくても、モックサーバーを使用できます。モックサーバーはOpenAPIドキュメントの仕様を満たすようなダミーデータを返却します。

APIごとにMockサーバーのURLが書いてあります。アクセスするとランダムのダミーデータが入ったレスポンスを取得できます。

モックサーバーを使うことで、APIの実装を待たずにAPIを呼び出すプログラムの開発ができます。

APIへリクエストして結果を確認できる

Swagger UIでは任意のリクエストを作成し、結果を確認できます。Stoplight StudioTry Itタブでも同じことができます。

エンドポイントには、先ほどのモックサーバーを選ぶこともできます。

また、各言語ごとのサンプルコードも併せて表示できます。

📜まとめ

REST APIのスキーマ駆動開発をするにあたり、『OpenAPIドキュメントのYAMLファイルを編集するのが大変』という問題を解決するため、Stoplight Studioを紹介しました。

OpenAPIドキュメントの編集だけでなく、API仕様書のプレビュー、REST APIクライアント、モックサーバーとしての機能もあり、APIを利用する開発者にも便利です。

現代では、ほとんどの開発がREST APIに関係すると思いますので、よろしければお試しください。