Stoplight Studioを使ってREST APIのスキーマ駆動開発に対するハードルを下げる

NAVITIME_Tech

2022年5月19日 19:09

こんにちは、みみぞうです。
ナビタイムジャパンで『システムや開発環境、チームの改善』を担当しています。

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

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

OpenAPIドキュメントを更新
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