Zenn
Open5

スキーマ駆動開発について学習＆調査

GraphQL
OpenAPI
MasaHeroMasaHero

現在自分が参画している案件でスキーマ駆動開発で行っているので，調べつつ学習する

MasaHeroMasaHero

参考書籍:WEB+DB PRESS vol.108 2019
3年以上ということもあって，古い情報であることも留意しつつ，この書籍でベースの基本知識を学んでいく。

MasaHeroMasaHero

Web APIの分類

  • SSKDs ... 特定少数の開発者
    • 例:開発チーム内部で利用するAPI
  • LSUDs ... 不特定多数の開発者
    • 例:外部に公開して利用してもらうAPI

スキーマ駆動開発におけるWebAPI開発でのメリット

開発効率の向上

  • クライアント側の開発とサーバの開発が非同期で進められる
    • クライアントへ渡すデータが先に決まっていたら，クライアント側は，WebAPIの実装完了を待たずに開発を進められる
      • スタブサーバでテストが可能
  • スキーマがそのままドキュメントとして活かせるので，これを基にクライアントとサーバ間で相談・調整がしやすい
  • ドキュメントが自動的に生成される(OpenAPIのSwaggerUI)
MasaHeroMasaHero

https://oai.github.io/Documentation/

OpenAPIのスキーマ構造内のオブジェクト一部

JSON形式からYAML形式のどちらかで作られる。
https://spec.openapis.org/oas/v3.1.0#openapi-object
オブジェクト単位で階層構造となっている。

  • openapi
    • info
    • servers
    • paths

info

メタデータを格納するオブジェクト。
APIの名前・説明・概要，バージョン情報，連絡先，ライセンス情報など

{
  "title": "Sample Pet Store App",
  "summary": "A pet store manager.",
  "description": "This is a sample server for a pet store.",
  "termsOfService": "https://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "https://www.example.com/support",
    "email": "support@example.com"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

https://spec.openapis.org/oas/v3.1.0#info-object-example

servers

APIサーバーの情報について記載されている。(URL・概要など)
本番・ステージング・ローカルなど複数指定できる。

paths

エンドポイント毎のAPI仕様(リクエスト・レスポンス)について記載されている。
pathsオブジェクトの中で階層が分けられている。

  • Paths
    • PathItem
      • Operation
        パスをキーにして複数のPathItemオブジェクトを持ち，PathIteｍオブジェクト内に複数のOperationオブジェクト(HTTPメソッド)を持つ。

{
  "/pets": {
    "get": { 
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {          
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}

YAMLの方が若干見やすい。

/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'

Operationオブジェクト内に$refがあるが，これはリファレンスオブジェクトと別オブジェクトへの参照。これにより，重複の記載を防ぐ。
今回の場合，Componentsオブジェクト内に記載された/schemas/petを参照している。

Components

再利用されるリクエストボディ・レスポンスをここに記載する。

Schemaオブジェクト

リクエスト・レスポンスで使うデータの型や構造を定義する。

Properties field

そのオブジェクトが持つプロパティが記載されている。

  • example
    • 具体的な値の例
  • xml

Parameter

APIサーバーに送信するパラメータを定義するオブジェクト。

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "integer",
      "format": "int64"
    }
  },
  "style": "simple"
}

Request Body

Response