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」をインストールします。
ちなみにブラウザの場合は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でプラスジャムを見つけてくださった方は、お時間あればコーポレートサイトや他の記事もご覧いただければ幸いです。
\コーポレートサイトはこちら/
\関連記事はこちら/