はじめに

今回はVisual Studio CodeでOpenAPIを利用する手順を簡単に紹介しようと思います。Swagger Editor（https://editor.swagger.io/）も利用できますが、ローカルで作業してバージョン管理に組み込みたかったのでOpenAPI (Swagger) Editorを導入してみました。

OpenAPIとは

OpenAPIはRESTful APIの仕様を記述するフォーマットのことをいいます。YAMLかJSON形式で記述します。
決まったフォーマットなので開発者間で書き方を統一できたり、Excelやドキュメントなどのツールに比べてバージョン管理が楽にできます。
この記事ではVisual Studio Codeに拡張機能を入れてYAML形式で書いていく方法とOpenAPIの基本的な構造を紹介します。

OpenAPIとSwaggerについて
OpenAPIが仕様やフォーマットのことで、SwaggerはOpenAPIのフォーマットで仕様を書いたり実行するためのツールのことです。
こちらの記事を参考にしました。
https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/

Visual Studio Codeの環境を構築

VSCodeでOpenAPIを記述するためにまずは拡張機能を入れます。
サイドメニューの拡張機能から、「openapi」で検索し「OpenAPI (Swagger) Editor」をインストールします。

ちなみにブラウザの場合はSwagger Editorを使って書くこともできます。
https://editor.swagger.io/

OpenAPI Editorで可視化

ではテスト用のAPIを作成します。
cmd + shift + pでコマンドパレットを開いて「new openapi」と入力します。

今回はv3.0のYAML形式で書くので一番上の「Create new OpenAPI v3.0 file (YAML)」を選択します。

以下のようなサンプルコードが出力されると思います。

この状態で試しに右上のプレビューアイコンをクリックします。

画面右にAPIの仕様をもとにプレビューが表示されます。GUIでAPI定義を確認しながら記述できます。

OpenAPIの構造

openapi（必須）
OpenAPIのバージョン情報をセマンティックバージョニングで記述します。

openapi: 3.0.2

info（必須）
infoセクションにはAPIの基本情報を記述します。：タイトル、説明（省略可）、バージョン

info:
  title: Sample API
  description: サンプルAPIです。
  version: 1.0.0

servers
serversセクションではAPIを提供するサーバーについて記述します。環境ごとに情報を記述できます。

servers:
  - url: http://api.example.com/v1
    description: 本番環境
  - url: http://staging-api.example.com
    description: ステージング環境

paths（必須）
pathsセクションでは各エンドポイントとHTTPメソッドを定義します。

paths:
  /users:
    get:
      summary: "ユーザーの一覧取得"
      description: "ユーザーの一覧を返します。"
      parameters: # リクエストパラメータを定義
        ...
      requestBody: # リクエストボディを定義
        ...
      responses: # レスポンスを定義
        ...

✅ parameters
リクエストのパラメータ情報を詳細に定義します。下記はユーザーの詳細情報を取得するAPIの例です。
パスパラメータで必須のユーザーIDをintegerで要求しています。

  /users/{userId}:
    get:
      parameters:
        - name: userId
          in: path
          required: true
          description: "取得するユーザーのID"
          schema:
            type : integer
            minimum: 1

✅ requestBody
リクエストで送信するボディの内容を定義します。下記は新しいユーザーを作成するリクエストの例です。

    post:
      summary: "新しいユーザーを作成"
      description: "新規登録時に新しいユーザー情報を追加します。"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: "ユーザー名"
                description:
                  type: string
                  description: "概要"
            example:
              name: "山田太郎"
              description: "ユーザーの説明"

✅ responses
ステータスコードごとにレスポンス形式を定義します。

responses:
    "200":
        description: "新しいユーザーを作成しました。"
        content:
        ...
    "400":
        description: "不正なリクエストです。"
        ...

そのほかsecurityでAPIのセキュリティ情報（OAuthなど）なども記述できます。
https://swagger.io/docs/specification/basic-structure/

まとめ

Visual Studio Codeに拡張機能を入れてYAMLを作成する方法とOpenAPIの構造についてまとめました。
API開発にOpenAPIを導入することで仕様を直感的に確認できたりgitでバージョン管理できるので、より効率的に開発、管理していけると思います。

最後まで読んでいただきありがとうございました！

✙

プラスジャムはWeb制作会社です。
ウェブサイト制作、システム開発、Webマーケティングなど、さまざまな課題解決やアイデアを具現化するWebソリューションを提案・提供しています。

noteでプラスジャムを見つけてくださった方は、お時間あればコーポレートサイトや他の記事もご覧いただければ幸いです。

＼コーポレートサイトはこちら／

＼関連記事はこちら／