Swaggerを利用することでREST APIの仕様を文章化できます。
今回はREST APIの仕様書であるSwagger Specの内容をSwagger UI、Swagger Editorに反映させる方法について紹介します。
目次
下準備: Swagger Specをローカル環境に用意する
Swagger SpecとはREST APIの仕様を文章化したものです。
今回は~/swagger/sample.yaml
というファイル名で、以下のようなSwagger Specを用意しました。
swagger: "2.0"
info:
description: "This is a sample API."
version: "1.0.0"
title: "Sample API"
host: "localhost:3000"
basePath: "/api/v1"
tags:
- name: "todo"
description: "Everything about todos"
schemes:
- "http"
paths:
/todos/{todoId}:
get:
tags:
- "todo"
summary: "Find todo by ID"
description: "Returns a single id"
operationId: "getTodoById"
produces:
- "application/json"
parameters:
- name: "todoId"
in: "path"
description: "ID of todo to return"
required: true
type: "integer"
format: "int64"
responses:
200:
description: "successful operation"
404:
description: "Todo not found"
Swagger Specの情報をSwagger UIに反映させる方法
Swagger UIとはSwagger Specの情報を反映させた静的ページを生成するツールのことを言います。
Swagger UIはSwagger Specの情報を可視化するだけでなく、画面上からREST APIを実行する機能も提供しています。
今回はDockerを利用してSwagger UIの環境を構築します。
swagger-uiのインストール手順1を参考に、以下のコマンドを実行します。
$ cd ~/swagger
$ docker run -p 80:8080 -e SWAGGER_JSON=/sample.yaml -v ~/swagger/sample.yaml:/sample.yaml swaggerapi/swagger-ui
docker run
コマンドについて補足説明をします。
-v
オプションを利用して、ローカル環境(ホスト)の~/swagger/sample.yaml
をコンテナの/sample.yaml
にコピーします。
SWAGGER_JSON
という環境変数にはSwagger UIに反映させるSwagger Specのファイル名を指定します。
-v
オプションによってローカル環境のSwagger Specがコンテナの/sample.yaml
に配置されているため、コンテナのSwagger UIにローカルのSwagger Specの内容が反映されます。
-p
オプションでホストの80番ポートとコンテナの8080番ポートを紐づけているため、http://localhost
にアクセスすると以下のような画面が表示されます。
Swagger Specの情報をSwagger Editorに反映させる方法
Swagger EditorとはSwagger Specを編集するエディタのことを言います。
Swagger Editorを利用することでSwagger Specを修正しながらSwagger UIの変化をリアルタイムで見られます。
Dockerを利用する方法
swagger-editorのインストール手順2を参考に、以下のコマンドを実行します。
$ cd ~/swagger
$ docker run -p 81:8080 -e SWAGGER_FILE=/sample.yaml -v ~/swagger/sample.yaml:/sample.yaml swaggerapi/swagger-editor
今回の例ではホストの81番ポートで紐付けを行っているため、http://localhost:81
にアクセスすると以下のような画面が表示されます。
Visual Studio Codeのプラグインを利用する方法
Dockerを利用してSwagger Editorを起動する場合、デフォルトのままではSwagger Editor上で修正したSwagger Specの内容がローカルに同期されません。
Visual Studio Codeを利用している場合はSwagger Viewerというプラグインを利用する方法がオススメです。
Swagger Viewerを利用すると、以下のような感じでSwagger UIを見ながらSwagger SpecをVisual Studio Code上で修正できます。
まとめ
以上でSwagger UIとSwagger Editorの環境構築手順の紹介を終わります。
この記事がいいなと思いましたらTwitter(@nishina555)のフォローもよろしくお願いします!