Swagger-uiの読み込みファイルを変更する。(AWS/Docker利用)

10404 ワード
YAML swagger AWS swagger-ui Docker AWS テキストリンク

目的

Swagger-uiを導入すると、初めは下記画像のようにペットショップのファイルが自動で読み込まれます。

今回は、swagger-uiに任意のファイルを読み込ませる方法を書きます。
AWS/EC2を使用しますが、ローカルでも同じ方法で変更できると思います。

前提条件

  1. AWS/EC2作成済み・SSH接続可能
  2. nginxをインストール済
  3. swagger-uiを利用可能(Docker)

1の設定がまだの方は、こちら。

2の設定がまだの方は、こちら。

3の設定がまだの方は、こちら。

1.任意のyamlファイルを置くディレクトリを作成する。

今回、私はec2上に/home/ec2-user/wwwのディレクトリを作成します。

mkdir.ec2
sudo mkdir /home/ec2-user/www

2.読み込ませたいファイルを作成

先ほど作成したディレクトリ直下に好きなyamlファイルを作成しましょう。
今回は、こちらの記事に載っていたyamlファイルを使用させていただきます。

pet.yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: ペットストア(変更後)
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: "pochi"
        tag:
          type: string
          example: "dog"
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

3.swagger-uiを起動する

swagger-uiを任意のファイルを読み込むように設定して、起動します。

swagger-ui.docker
sudo docker run -d -p 8001:8080 -e SWAGGER_JSON=/tmp/pet.yaml -v /home/ec2-user/www:/tmp swaggerapi/swagger-ui

4.swagger-uiを確認する

nginx.confで指定したswagger-uiのURLにアクセスする

nginx.confの設定がまだの方は、こちら

すると、下記画像のように、最初のペットショップのファイルから、今回用意したyamlファイルに変更されているはずです。

注意点

①すでにswagger-uiをDocker runしている場合は、一度停止してから再度起動してください。

起動中のコンテナ検索
sudo docker ps
コンテナ停止
sudo docker stop (コンテナ名)

②SWAGGER_JSONの指定の仕方

ボリュームを作成する

Dockerにはボリュームと呼ばれるデータを保存できる場所があります。
そのボリュームから、任意のyamlファイルを指定して、swagger-uiに読み込ませる必要があります。

しかし、ボリュームは最初から自動的には使えません。
下記オプションを使って、自分で用意する必要があります。

-v /home/ec2-user/www:/tmp

この「-v」 のオプションが、ボリュームを作成しますよという合図です。
簡単に説明すると、ec2上の/home/ec2-user/wwwのディレクトリ内にあるファイルを、
/tmpというボリュームにコピーして使えるようにしますよということです。

今回でいうと、/home/ec2-user/www直下には、yamlファイル(pet.yaml)が１つ作成されているので、/tmp直下(ボリューム内)にも同じyamlファイル(pet.yaml)が１つ作成されています。

SWAGGER_JSONにボリューム内のファイルを指定
SWAGGER_JSON=/tmp/pet.yaml

ちなみに、/home/ec2-user/www や　/tmp　は自分が好きなディレクトリを指定することができます。

最後に

以上が、Dockerを使用したswagger-uiの読み込みファイルの変更方法です。

不明点、質問などあれば、気軽にコメントをお願い致します。