📳

OpenAPIでの設計方法?

2024/01/14に公開

Swagger

OpenAPI

tech

読んでほしい人

OpenAPIを使ってみたい人.
YAMLのファイルに興味がある人.
実はYAMLのファイルに興味を持たなくて良いです。人間が読むものではない😇

補足情報

今回は、{JSON} PlaceholderというサイトのusersのエンドポイントのAPIを使って、JSONのコードを元に、yamlでAPIの仕様書を作るのをやってみようと思います。

VScodeだとPreviewする便利な機能があるので、入れておくと作業がしやすくなります。ブラウザを開かなくても動作の確認ができます。

これを追加!

command + shift + pで探す。yamlのファイルで実行しないとプレビューはできないので注意!

OpenAPIとは?
https://learn.openapis.org/

日本語に翻訳した解説

対象とする訪問者

このガイドは、API をOpenAPI description ( OAD ) で形式化することでメリットを享受したいと考えているHTTP ベースの API設計者および作成者を対象としています。

機械可読な API 記述は今日どこにでも普及しており、OpenAPI は新しい API を記述するために最も広く採用されている業界標準です。したがって、最初からそれを学び、正しく習得する価値があります。

これらのページはOpenAPI 仕様(OAS)の付属品であり、読者が OAS を学習するのに役立ち、「…を達成するための最良の方法は何ですか?」などの質問に答えます。または「…の目的は何ですか?」それらは当然仕様の範囲外です。

このガイドがあなたに適しているかどうかわからない場合は、以下の次のセクションをお読みください。
「API」、「機械可読記述」、「OpenAPI」の意味がわからない場合は、まず「はじめに」の章を読んでください。
OpenAPI の説明を初めて作成する場合は、「OpenAPI 仕様の説明」の章で段階的なチュートリアルをお読みください。
すでにOpenAPI の経験があるものの、特定のトピックについてサポートが必要な場合は、「OpenAPI 仕様の説明」の章の索引を参照してください。高度なトピックも含まれています。
最後に、 OpenAPIを最大限に活用するために推奨されるベストプラクティスを必ず理解してください。
そしてもちろん、いつでも実際のOpenAPI 仕様を参照することができます。

OpenAPIを使用する利点

API を機械可読形式で正式に記述すると、自動ツールで API を処理できるようになり、次のことへの扉が即座に開きます。

説明の検証とリンティング: 説明ファイルが構文的に正しく、仕様の特定のバージョンとチームの残りのフォーマットガイドラインに準拠していることを確認します。
データ検証: 開発中およびデプロイ後に、API を介して流れるデータ (両方向) が正しいことを確認します。
ドキュメントの生成: 機械可読な記述に基づいて人間が読める従来のドキュメントを作成し、常に最新の状態に保ちます。
コード生成: 任意のプログラミング言語でサーバーコードとクライアントコードの両方を作成することで、開発者はデータ検証を実行したり、SDK グルーコードを作成したりする必要がなくなります。
グラフィカルエディタ: 説明ファイルを手で入力する代わりに、GUI を使用して簡単に作成できます。
モックサーバー: コードを 1 行記述する前に、テストを開始できるサンプル応答を提供する偽のサーバーを作成します。
セキュリティ分析: 潜在的な脆弱性をずっと後ではなく、API 設計段階で発見します。
これに加えて、OpenAPI 仕様では次の機能も提供されます。
独自フォーマットではない: 仕様の将来の方向性について発言権があります。
最も開発されたツールエコシステム: 前のステートメントの直接の結果として、OpenAPI は連携する膨大な数のツールを提供します。OpenAPI ツールをざっと見てみましょう。
機械と人間の両方が読み取り可能な形式: OAD を手動で作成するのは最も便利な方法ではありませんが ( 「ベストプラクティス」を参照)、OAD はプレーンテキストファイルなので、何かをデバッグする必要がある場合に簡単に参照できます。
このページの上部にあるリストから希望のエントリーポイントを選択して、旅を始めましょう。

記事の内容

AIの力を借りて、JSONのデータをYAMLに変換して、OpenAPIのファイルを作成しました。HTTP GETをして、全てのデータの取得と、特定のidを検索するAPI仕様書になっております。

JSONファイルを元にYAMLを作成

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
servers:
  - url: https://jsonplaceholder.typicode.com
paths:
  /users:
    get:
      summary: Get a list of users
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      summary: Get a user by ID
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: The id of the user to retrieve
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        username:
          type: string
        email:
          type: string
        address:
          type: object
          properties:
            street:
              type: string
            suite:
              type: string
            city:
              type: string
            zipcode:
              type: string
            geo:
              type: object
              properties:
                lat:
                  type: string
                lng:
                  type: string
        phone:
          type: string
        website:
          type: string
        company:
          type: object
          properties:
            name:
              type: string
            catchPhrase:
              type: string
            bs:
              type: string

OpenAPIのyamlファイルは、RESTful APIの仕様を定義するための言語です。このファイルは以下の主要なセクションで構成されています。

openapi: これは使用しているOpenAPIのバージョンを示します。ここでは3.0.0が使用されています。
info: APIの基本情報を提供します。これには、APIのタイトルとバージョンが含まれます。
servers: APIがホストされるサーバーのURLを定義します。
paths: APIのエンドポイントと、それらのエンドポイントで利用可能なHTTPメソッド（GET、POST、PUT、DELETEなど）を定義します。各メソッドは、その操作の概要、パラメータ、および応答を定義します。
components/schemas: APIで使用されるデータモデルを定義します。これは、リクエストボディやレスポンスボディの形式を定義するために使用されます。

この特定のyamlファイルでは、/usersと/users/{id}の2つのエンドポイントが定義されています。/usersエンドポイントは、ユーザーのリストを取得するためのもので、/users/{id}エンドポイントは、特定のIDを持つユーザーを取得するためのものです。また、components/schemas/Userでは、ユーザーのデータモデルが定義されています。