Laravel・PHP入門

PHPer初心者

【API】【Swagger】Swaggerをモックサーバとして機能させるまで

Swagger 入門 導入 API

今回、サーバ・フロントの完全分業実現のため Swaggerを導入し、APIの仕様を管理、かつモックサーバとして機能させることに。

仕様を決める→モックサーバとして動作させるまでの流れメモ。

動作確認環境

Mac OS X以上 Swagger2.0 (Open APIは3.0が最新ですがswagger-codegen使用のため2.0を使用) はやく3.0対応してほしみ。。。

流れ

※色々インストールなどの前準備※ ①API仕様をSwagger形式(yaml)で記載、 ②Swagger-Codegenを使用してnode.jsのプロジェクトへ変換 ③サーバ起動 →モックサーバとしてブラウザ上での確認、 自分のプロジェクトからもレスポンス確認ができる

良いこと： * Githubでyamlファイルのみの管理で良い * コマンド一つでモックサーバが起動する

悪いこと： * 仕様書を書き換えるたびにプロジェクトの上書きが必要 * サーバ必要

前準備(brew/npmは入ってる前提)

＠任意のdirで(今回は/Users/ユーザ名/swagger/) * javaのinstall(入っていなければ) brew cask install caskroom/versions/java8

  • swagger-codegenのinstall brew install swagger-codegen

swagger形式のAPI仕様書作成

  • swagger.yamlファイルの作成(名前は任意、api1.yamlなどでもOK) vi swagger.yaml
swagger: '2.0'

// モックのメタデータを記述する
info:
  description: |
    This is a sample server Petstore server.  You can find
    out more about Swagger at
    [http://swagger.io](http://swagger.io) or on
    [irc.freenode.net, #swagger](http://swagger.io/irc/).
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

// モックサーバーのプロトコルの選択
schemes:
- http

// エンドポイントの記述
paths:
  /pet/{petId}:
    get:
      tags:
      - pet
      summary: Find pet by ID
      description: Returns a single pet
      operationId: getPetById
      produces:
      - application/json
      parameters:
      - name: petId
        in: path
        description: ID of pet to return
        required: true
        type: integer
        format: int64
      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/Pet'
        400:
          description: Invalid ID supplied
        404:
          description: Pet not found

// モデル定義の記述
definitions:
  Category:
    type: object

    // モデルの詳細定義
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
  Tag:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
  Pet:
    type: object
    required:
    - name
    - photoUrls
    properties:
      id:
        type: integer
        format: int64
      category:
        $ref: '#/definitions/Category'
      name:
        type: string
        # 各値の例の記述
        example: doggie
      photoUrls:
        type: array
        items:
          type: string
      tags:
        type: array
        items:
          $ref: '#/definitions/Tag'
      status:
        type: string
        description: pet status in the store
        enum:
        - available
        - pending
        - sold
  • swagger codegenコマンドで、yamlファイルから任意のディレクトリ内にモックサーバのプロジェクト生成(今回はnodejsで作ってます)

mkdir codegen-test/

swagger-codegen generate -i swagger.yaml -l nodejs-server -o codegen-test/

※codegen-test は任意のディレクトリ名でok

  • プロジェクト生成後、パッケージ諸々インストールして、モックサーバ起動
cd codegen-test
npm install
node index.js
Your server is listening on port 8080 (http://localhost:8080)
Swagger-ui is available on http://localhost:8080/docs

こんなレスポンスが帰って来れば、localhost:8080/docsへアクセスすれば swagger-ui上でテストできます！

一度作った仕様書も、更新した後はもう一度node.jsファイルへ変換してあげれば 既に作ったプロジェクトの中身が全部更新されます

OpenAPI3.0になるとかなり変わるので、 今度そのあたりもまとめたいなー かなりハマったのが2.0と3.0の違いでした。。。

ちなみに今は配列でのレスポンス、ファイルの結合とかで苦労してました phpでyaml結合ツールつくるしかないかなー とりあえず一連のモックサーバ起動までの流れをshellかこう。

ではまた！