Zenn
🔰

Open API 入門 Part1 | 基本的な書き方

2024/05/21に公開
API
frontend
OpenAPI
backend
tech

最近さまざまなところで、OpenAPIを使っているのを見かけるようになったので
そもそもOpenAPIってなんだっけ？
これが担っている役割やメリットはなんだろう？
を深掘りしていきます！

OpenAPIとは

HTTP API定義の仕様を標準化しているもの.
参考

メリット

  • API仕様の標準化なので、バックエンド・フロントエンド間の共通認識がコードによって定義できる
  • 仕様書からAPI通信部分のクライアントコードを自動生成してくれるライブラリがある
  • モックサーバーも生成することができる

コードの読み方

参考
仕様書はJSONまたは、YAML形式で書きます.
YAML形式で書かれることとが多いので、YAMLで書きます.
(YAMLの方がファイルサイズが削減される・コメントを書くことができる・ダブルクオートで囲む必要がない)

openapi.yaml
openapi: 3.1.0
info:
  title: MyAPI
  version: 0.0.1
paths: {}

これが最小構成になります.
OpenAPIオブジェクトとして下記の3つが必要です.

  • openapi: OpenAPIのバージョン
  • info: APIに関する情報
  • paths: APIエンドポイントに関する情報

そして、pathsの中身にリクエストやレスポンスの情報を書いていくことになります.

openapi.yaml
openapi: 3.1.0
info:
  title: MyAPI
  version: 0.0.1
paths:
  /posts:
    get:
      responses:
        "200":
          description: post response
          content:
            application/json:
              schema:
                type: array
                items: 
                  type: object
                  properties:
                    text:
                      type: string
                    imgSrc:
                      type: string
        "400":
          schema:
            type: object
            properties:
              message:
                type: string

レスポンスの基本的な書き方を追加してみました.
書き方の手順としては

  1. pathsの下は、APIエンドポイントごとに区切る
  2. HTTPメソッドごとに区切る
  3. レスポンスの種類ごとに区切る
  4. 返すコンテンツのスキーマを書く
    の順番で記述します.

schemaの構造
上記の200レスポンスは

[
    {
        "text": "hogehoge",
        "imgSrc": "https://example.com/hoghoge.img"
    }
]

のようなJSONを返す構造になっている.

扱えるデータ型 (type)

  • String
  • Number
  • Boolean
  • Array
  • Object
  • null

まとめ

今回は、OpenAPIの基本的な書き方を中心に学習してみました.
次回は、schema定義の部分をさらに綺麗に書く方法を紹介します！お楽しみに！！

Discussion