見出し画像

Visual Studio CodeでOpenAPI (Swagger) Editorを使用

はじめに

今回は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」をインストールします。

OpenAPI Editorの拡張機能

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

OpenAPI Editorで可視化

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

(YAML)がついていないのはJSON形式です

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

\コーポレートサイトはこちら/

\関連記事はこちら/

プラスジャム製作開発部メンバーがWeb制作技術を紹介。
案件で実装した機能や自己学習で得た知識を発信していきます。
[今回の記事担当]バックエンドエンジニア k.m