Help us understand the problem. What is going on with this article?

Swagger EditorとSwagger UIとSwaggerのモックAPIサーバーをdocker-compose化してみた

More than 1 year has passed since last update.

07d4ffed-2dbf-4829-ab18-ef27f6877261.png

背景

初投稿です。イレブンナインの松田です。@matsudachikara2
最近、社内でAPIの仕様をどうやって管理、共有していくかを検討してました。そこで、Swaggerを使うのがいい感じらしい!ということを聞き、調査を始めましたが、個々のツールの使い方や導入は出てくるものの、具体的にチームで共有、管理まではどうやってするのかいまいち分かりませんでした。
調べていくとSwaggerHubなどのプラットフォームを使うのが一般的みたいでしたが、もっと簡単にSwagger EditorとSwagger UIとSwaggerのモックAPIサーバーを使えたらなということで作ってみました。

Swaggerとは?

こちらはとても良い記事がすでにありますので、そちらを見ると良いと思います!

公開リポジトリ

swagger-all-in-one-docker-container

概要

Swagger EditorとSwagger UIとSwaggerのモックAPIサーバー(openapi: 3.x)を手軽に同時に環境に立ち上げられるようdocker-compose化してみました
もしswagger specをswagger: "2.0"形式で書きたい場合はswagger2.0branchをお使いください
このコンテナには初期でサンプルのswagger specが入っていて、editor, ui, api, nginxが初期状態で立ち上がり、最初から設定無しで起動出来るようになってます
あとはEditorでopenapi.jsonを保存しコンテナを立ち上げ直すだけで、UIとモックAPIサーバーを最新に更新していくことが出来ます

起動方法

docker-compose up -d

こんな感じで起動します
docker-compose ps
         Name                       Command               State           Ports
----------------------------------------------------------------------------------------
swagger-api      /usr/local/bin/apisprout / ...   Up      0.0.0.0:8083->8000/tcp
swagger-editor   sh /usr/share/nginx/docker ...   Up      0.0.0.0:8081->8080/tcp
swagger-nginx    nginx -g daemon off;             Up      80/tcp, 0.0.0.0:8084->8084/tcp
swagger-ui       sh /usr/share/nginx/docker ...   Up      0.0.0.0:8082->8080/tcp

使い方

  1. swagger-editorでswagger specを編集
  2. swagger specをjson形式でswagger-editorの画面から保存
  3. 保存したjsonをswagger/openapi.jsonに移動
  4. docker-compose restartでswagger-uiとswagger-api(mock server)に変更が反映される
  5. もしswagger-editorで外部ファイルを読み込みたい場合は、画面内File > Import Fileから読み込む

注意

  • http://localhost:8082/で参照するとキャッシュで変更が反映されない場合があるのでhttp://127.0.0.1:8082/で参照した方が良い(apiも同様)
  • swagger-apiの起動に失敗した場合は、swagger/openapi.jsonからモックAPIの立ち上げに失敗した可能性が高いので、docker logsなどでデバッグし、openapi.jsonを直してから立ち上げ直す
  • swagger-apiを他ドメインからアクセスしたい場合は(CORS対策)、swagger-nginx経由でswagger-apiにアクセスする

swagger-editor

  • swagger specを編集出来る
  • swagger specはjson, yaml形式などにしてエクスポート出来て、swagger-uiから参照するとドキュメントとして見れる。swagger-apiからjsonを参照するとモックAPIサーバーになる

swagger-ui

  • swagger specをドキュメントとして見れる
  • swagger specは環境変数でjsonファイルまたは、API_URLからjsonを参照できる environment: SWAGGER_JSON: /openapi.json # API_URL: ""
  • このレポジトリの./swagger/openapi.jsonが参照先になっている

swagger-api(apisprout)

  • 内部的にapisproutを使用しています
  • swagger specはopenapi: 3.xに対応しています
  • こちらも./swagger/openapi.jsonが参照先になっている
  • ただしapisproutがヘッダーにAccess-Control-Allow-Originを付けてくれないので、前段にnginxを置き、ヘッダーを付与してAPIにプロキシしています。(他ドメインからAPIにアクセスできないと不便なので。CORS対策。)

swagger-nginx

  • ヘッダー修正用に配置
  • 8084portでnginx経由でモックAPI(swagger-api)にアクセス出来ます。
  • curl等で叩けます
  * 
  curl -i -X GET http://127.0.0.1:8084/pets/1 -H "accept: application/json"

  HTTP/1.1 200 OK
  Server: nginx/1.15.3
  Date: Thu, 04 Oct 2018 07:58:19 GMT
  Content-Type: application/json
  Content-Length: 49
  Connection: keep-alive
  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: POST, GET, PATCH, DELETE, PUT, OPTIONS
  Access-Control-Allow-Headers: Origin, Authorization, Accept
  Access-Control-Allow-Credentials: true

  {
    "id": 1,
    "name": "doggie",
    "tag": "dog"
  }

追記

2018/08/01

swagger specの記述をswagger: "2.0"からopenapi": "3.x"に変更しました。
理由としては、自社で実際にswagger specを作成、編集してみてopenapi": "3.x"の方が、圧倒的に書きやすかった為です。
それに合わせてmock apiのコンテナの中身を変更、docker-compose.yml等も修正しました。
注意としては、mock apiのみopenapi": "3.x"記述方式でしか動かなくなっております。
もしswagger: "2.0"形式で記述したい場合はswagger2.0ブランチを用意したのでそちらからご使用ください。

2018/10/04

他ドメインからAPIにアクセスできないと不便なので(CORS対策)、nginxのコンテナを追加しました。
apisproutがヘッダーにAccess-Control-Allow-Origin
を付けてくれないので、前段にnginxを置き、ヘッダーを付与してAPIにプロキシしています。
8084portでnginx経由でモックAPIにアクセス出来ます。
SNSが苦手ということでリンクしませんが、木梨さんというスーパーエンジニアの方にサクッと直してもらいました。 Special Thanks to Kinashi!

変更前

$ curl -i -X GET http://127.0.0.1:8083/pets/1 -H "accept: application/json"
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 04 Oct 2018 07:36:15 GMT
Content-Length: 49

{
  "id": 1,
  "name": "doggie",
  "tag": "dog"
}
変更後

$ curl -i -X GET http://127.0.0.1:8084/pets/1 -H "accept: application/json"
HTTP/1.1 200 OK
Server: nginx/1.15.3
Date: Thu, 04 Oct 2018 07:36:18 GMT
Content-Type: application/json
Content-Length: 49
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, PATCH, DELETE, PUT, OPTIONS
Access-Control-Allow-Headers: Origin, Authorization, Accept
Access-Control-Allow-Credentials: true

{
  "id": 1,
  "name": "doggie",
  "tag": "dog"
}
elevennines
“CO-DESIGN”=一緒に実現する、一緒に解決する私たちは、実現したい、解決したいことのある「あなた」と、それを達成するまでの道筋を“CO-DESIGN”します。
https://www.elevennines.co.jp/
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした