swagger.yaml/jsonをローカル環境のSwagger Editorで操作する

Oct 10, 2020 20:40 · 1035 words · 3 minute read docker swagger

editor.swagger.io にブラウザからアクセスすることで、環境構築をすることなくSwagger Editorを使うことができます。
しかし、扱うデータの性質やネットワーク状況に制限がある場合は、ローカルでSwagger Editorを実行することも可能です。
今回はDockerを使って、ローカルでSwagger Editorを動かし、swagger.yamlファイルを操作したので、手順を残しておきます。

目次

環境

Docker

Swaggerとは

Swaggerは、OpenAPI仕様に基づいたREST APIの構築、文書化、使用に便利なツールセットです。
APIの構造を設計すると、自動でAPIに関するドキュメントやクライアントライブラリ、テストツールを作成してくれます。

下記のようなツールが提供されています。

  • Swagger Editor: OpenAPI仕様のAPIを記述できるブラウザーベースのエディター
  • Swagger UI: OpenAPI仕様の記述から、APIのドキュメントを生成する
  • Swagger Codegen: OpenAPI仕様の記述から、サーバースタブとクライアントライブラリを生成する

参照:
What Is OpenAPI? > What Is Swagger?
What Is Swagger?

Docker Engineのインストール

環境に合わせたDocker Engineをインストールします。

Install Docker Desktop on Windows

Install Docker Desktop on Mac

今回はUbuntuの上でDockerを動かすので、下記のドキュメントに従ってDocker Engineをインストールします。

Install Docker Engine on Ubuntu

推奨されている「Install using the repository」でインストールします。

$ sudo apt update
$ sudo apt install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
$ sudo apt-key fingerprint 0EBFCD88
pub   rsa4096 2017-02-22 [SCEA]
      9DC8 5822 9FC7 DD38 854A  E2D8 8D81 803C 0EBF CD88
uid           [  不明  ] Docker Release (CE deb) <docker@docker.com>
sub   rsa4096 2017-02-22 [S]
$ sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"
$ sudo apt update
$ sudo apt install docker-ce docker-ce-cli containerd.io

dockerコマンドが使えることを確認します。

$ docker

Usage:	docker [OPTIONS] COMMAND

A self-sufficient runtime for containers

Swagger Editorをローカルで起動

下記のコンテナを利用します。

docker hub swaggerapi/swagger-editor

$ sudo docker pull swaggerapi/swagger-editor
$ sudo docker run -d -p 80:8080 swaggerapi/swagger-editor

http://localhost/ にアクセスするとSwagger Editorを使うことができます。

最後に

Dockerを使うことで、とても簡単にSwagger Editorの環境を構築することができました。

本記事を書いている最中に知ったのですが、下記の記事で紹介されている「Stoplight Studio」と「Prism」もとても便利そうです。がっつりとSwaggerを触る機会がでてきたら、これらのツールを使ってみようと思います。

本当に使ってよかったOpenAPI (Swagger) ツール

tweet Share