Swaggerを使ってモックサーバを立てるまでの手順 #swagger

この記事では以下の内容について記述しています。

Swaggerの基礎概念
Swagger Editorを使ったAPIのドキュメント作成
Swaggerで作成したAPIのドキュメントを元にモックサーバを立てる

`Swagger`とは?

Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

SwaggerはOpenAPI（OAS）のための世界最大のAPI開発フレームワークであり、APIのライフサイクル全体にわたって、設計からドキュメント化、テストおよびデプロイまでを可能にします。

という事なので、APIの仕様設計だけではなく、テストやデプロイまでしてくれる便利ツールです。

基本用語

Swaggerを学ぶと色んな用語があっちこっち飛んでくるので、先にここで話をまとめておきます。
今回は必要最低限の用語と使うやつの名前だけピックアップしました。

Swagger Specification
- Swaggerを扱う上で中心となる概念で、Swaggerの仕様に準じた、RESTful APIインターフェイスを記述するためのフォーマット(YAML/JSON)。
Swagger Editor
- Swagger Specificationのエディタ。慣れるまで時間がかかる。
Swagger UI
- Swagger Specificationから動的にドキュメントを生成するツール。とても見やすい。
Swagger Codegen
- Swagger Editorで作成した内容をそのままコードに書き出す。様々な言語に対応しており、言語だけでなくFWにも対応している。

`Swagger Editor`を使って`Swagger Specification`を作成し、APIの仕様を作成する。

詳細な文法はここを参照する。

PENAPI SPECIFICATION

ここでは@Fendo181が作成したlumenの簡単なAPIを例に作成していきます。

https://github.com/Fendo181/lumen_authors_api

# Get all authors 
GET /api/authors

# Get one author
GET /api/authors/23

#Create an author
POST /api/authors

#Edit an author
PUT /api/authors/23

# Delete an author
DELETE /api/authors/23

詳細:https://github.com/Fendo181/lumen_authors_api/issues/2

これを例にしてSwagger Editorでドキュメントを作成してみます。

swagger: '2.0'
info:
  description: |
    サンプルです. 
    
    You can findout 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: Lumen Authors API 
  contact:
    email: fendo181git@gmail.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
# host: petstore.swagger.io
# basePath: /v2

tags:
- name: authors
  description: Authors Info
  externalDocs:
    description: Find out more
    url: http://swagger.io
# schemes:
# - http
paths:
  /authors:
    get:
      tags:
      - authors
      summary: Get all author by id
      consumes:
      - application/json
      - application/xml
      produces:
      - application/json
      - application/xml
      responses:
        200:
          description: Successful
          schema:
           $ref: '#/definitions/Author'
    post:
      tags:
      - authors
      summary: Create an new author
      produces:
      - application/json
      - application/xml
      parameters:
      - in: body
        name: body
        description: Add New Author 
        required: true
        schema:
          $ref: '#/definitions/Author'
      responses:
        200:
          description: Success
  /authors/{id}:
    get:
      tags:
      - authors
      summary: Get an author by id
      produces:
      - application/json
      - application/xml
      parameters:
      - name: id
        in: path
        description: The id that needs to be fetched.  
        required: true
        type: string
      responses:
        200:
          description: successful 
          schema:
           $ref: '#/definitions/Author'
        400:
          description: Invalid id supplied
        404:
          description: User not found
    put:
      tags:
      - authors
      summary: Updated author by id
      description: Update Author info
      produces:
      - application/json
      - application/xml
      parameters:
      - name: id
        in: path
        description: name that need to be updated
        required: true
        type: string
      - in: body
        name: body
        description: Updated user object
        required: true
        schema:
          $ref: '#/definitions/Author'
      responses:
        200:
          description: author info
    delete:
      tags:
      - authors
      summary: Delete author by id
      description: This can only be done by the logged in user.
      produces:
      - application/json
      - application/xml
      parameters:
      - name: id
        in: path
        description: The name that needs to be deleted
        required: true
        type: string
      responses:
        200:
          description: Deleted Successfully
definitions:
  Author:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      email:
        type: string
      github:
        type: string
      twitter:
        type: string
      location:
        type: string
      latest_article_published:
        type: string
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
# Added by API Auto Mocking Plugin
host: virtserver.swaggerhub.com
basePath: /Fendo181/APP/1.0.0
schemes:
 - https
 - http

このymalで書かれたSwagger Specification（左）を元にSwagger UI(右)で簡単にAPIのドキュメントを生成する事が可能です。

この様に手順としてはSwagger EditerでSwagger Specificationを記述して、SwaggerUIを見ながら、APIの仕様を設計していく方針になると思います。

また作成したAPIはSwaggerHubで公開する事が可能です。

モックサーバを立てる。

SwaggerHubからサーバファイルを出力してモックサーバを構成してみましょう。SwaggerHubのserverから、指定の環境を選択してファイルを出力します。

今回はnodejs-serverで考えます。

中身の構成は以下の様になっている。

# tree nodejs-server-server-generated -L 1                                                                         [~/src/fendo181/lumen_authors_api][add-swagger-spec]
nodejs-server-server-generated
├── README.md
├── api
│   └── swagger.yaml  #swaggerファイル
├── controllers
│   └── Authors.js 
├── index.js
├── node_modules
├── package-lock.json
├── package.json
├── service
│   └── AuthorsService.js  
└── utils
    └── writer.js

swagger.yamlはSwaggerHubで記述したSwagger Specファイルがそのまま書き込まれています。
このswagger.yamlをもとにサーバの処理が記述されているのが、Authors.js です。
ここのAuthorsは任意の名前にになります。

ブラウザでSwagger UIを確認する。

npm installを実行する。

$ npm start                                                           

> lumen-authors-api@1.0.0 prestart /Users/futoshi.endo/src/fendo181/lumen_authors_api/nodejs-server-server-generated
> npm install
up to date in 0.797s

> lumen-authors-api@1.0.0 start /Users/futoshi.endo/src/fendo181/lumen_authors_api/nodejs-server-server-generated
> node index.js

Your server is listening on port 8080 (http://localhost:8080)
Swagger-ui is available on http://localhost:8080/docs

http://localhost:8080/docsにアクセスしてSwagger UIを確認します。

ここで各エンドポイント毎の処理を確認する事もできます。Try It Outでブラウザ上でResponseを確認する事ができます。試しにGETの処理を確認してみましょう。

curlで確認

GET

$ curl -X GET --header 'Accept: application/json' 'https://virtserver.swaggerhub.com/Fendo181/APP/1.0.0/authors'  
{
  "id" : 0,
  "name" : "string",
  "email" : "string",
  "github" : "string",
  "twitter" : "string",
  "location" : "string",
  "latest_article_published" : "string"
}

Swaggerを使ってモックサーバを立てるまでの手順

Swaggerとは?