OpenAPI3の定義ファイルを元にモックサーバを起動する

きっかけ

仕事でAPIドキュメントを記述する必要があったので、OpenAPI3.0の学習がてら、定義ファイルから簡単にモックサーバを起動することができないか、調べてみました。

前提条件

mac os 10.13 High Sierra
go langがインストール済

用意するもの

OpenAPI 3に準拠したAPIの定義ファイル
モックサーバソフトのAPIsprout

OpenAPI 3のAPI定義ファイルを作成する

どこか、適当なディレクトリにopenapi.ymlというファイルを作成し、以下のようなAPI定義ファイルを作成して下さい。以下のAPI定義ファイルは個人な学習用に作成した、book storeというAPIで/booksにアクセスすると本の一覧が返却されることを定義しています(公式のサンプル pet storeを元に作りました。

openapi: "3.0.0"
info:
  version: 1.0.3
  title: ブックストアのAPI
  description: これはブックストアAPIの詳細となります。
servers:
  - url: http://develop.bookstore.com/api
    description: development
paths:
  /books:
    get:
      description: 本の一覧取得
      operationId: findBooks
      parameters:
        - name: name
          in: query
          description: 本の名称を指定してください
          required: false
          style: form
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: 本の一覧
          content:
            application/json:
              schema:
                type: array
                items:
                  required:
                    - name
                      price
                  properties:
                    name:
                      type: string
                      description: 本の名前
                      example: 'book name1'
                    price:
                      type: string
                      description: 本の価格
                      example: 1000
                example:
                    - name: 'name1'
                      price: 300
                    - name: 'name2'
                      price: 500
                    - name: 'name3'
                      price: 1000

APIsproutのインストール

以下のコマンドでインストールします。

go get github.com/danielgtaylor/apisprout

API mock server起動

API定義ファイルを指定してAPIsproutを起動することでAPIにアクセスできるようになります。
デフォルトは8000ポートで、-p 8001とか指定することで違うポートで起動することもできます。

apisprout openapi.yml

起動したあとはもう１つターミナルを開いて下のコマンドを打ち込んだり、ブラウザでアクセスすると本の名前と値段のJSON配列が返却されると思います。
この配列はopenapi.ymlの最後にある、exampleに記述されているものが返却されてきます。

curl  http://localhost:8000/books

課題

APIsproutのhelpには--watchオプションで定義ファイルをreloadするみたいなことが記述されているのですが、実際にはreloadされないようでした。残念。

参考

こちらのサイトでyamlの基本的な構造などを解説されています。
https://techblog.zozo.com/entry/openapi3/go

APIsproutの紹介記事です。ここでAPIsproutの存在を知りました。
https://qiita.com/yoshi_detteiu/items/96b1a5698fecf8e0029e

miyazi888の覚え書き日記

学習したことを書き留めてます。