本イベントの流れ

• このイベントで得られること
• Swaggerとは何か？
• Swaggerの書き方
• 今回使用するAPIの説明
• ハンズオン&答え合わせ
• 質疑応答

このイベントで得られること

• Swaggerが何かわかる
• 何故Swaggerを使用するのか理解できる
• Swagger書き方が分かる

Swaggerとは何か？

• SwaggerはRESTful APIを構築するためのオープンソースのフレームワーク
• RESTful APIのインターフェイスの記述をするための標準フォーマットがSwagger
• SwaggerはYAML形式で記述すると自動的にドキュメント化してくれ、コードからドキュメント生成が可能になる
• コードで記述することでgithubでの管理も可能になるので変更履歴がわかりやすく、管理しやすくなる

Swaggerの書き方

• swagger
  Swaggerのバージョンを記述

• info
  タイトル・説明・バージョンなど、APIについての情報を記載

• paths
  APIのエントリポイントを記述
  ここに定義する情報をもとにエントリポイントが作成されるので重要な箇所
  pathsには下記のような階層形式で記載する

• pathのURL

  • HTTPメソッド（get,post,put,deleteなど）
    • エントリポイントのリクエストとレスポンスを記述

• parameters
  リクエストの際に渡すパラメーターを記述する

• name(string):パラメータ名

• in(string):パラメータの場所(query, header, path, formData, body)

• description(string): パラメータの説明

• required(boolean):必須パラメーターかどうかをtrueかfalseで記述

• schema(schema object):bodyのパラメーターをスキーマオブジェクトとして記述
  inがbodyである場合に必須

• type(string):パラメータのタイプ(string, number, integer, boolean, array, fileの中から選ぶ)
  inがbody以外である場合は必須

• format(string):パラメーターの型 ここから選ぶ

• responses
  返ってくるレスポンスを記述する

  • description(string):レスポンスの説明
  • schema(schema object):レスポンスのbody。スキーマオブジェクトで記述 詳しくはこちら
  • headers(headers object):レスポンスヘッダーを記述 詳しくはこちら
  • example(example object):レスポンスの例。レスポンスの値を自分で定義したい時に使う 詳しくはこちら

今回使用するAPIの説明

身長、体重を入れるとBMI、適正体重、肥満度を返してくれます！
APIの詳細は以下！

• https://us-central1-tub-89275.cloudfunctions.net/
• /getHealthcare
  • get
  • query_params
    • weight(必須)
      • integer
    • height(必須)
      • integer
  • response
    • 200(Json)
      • bmi : integer
      • suitable_weight : integer
      • degree_of_obesity : string
    • 400(Json)
      • error_message : string

• /postHealthcare
  • post
  • body_params
    • weight(必須)
      • integer
    • height(必須)
      • integer
  • response
    • 200(Json)
      • bmi : integer
      • suitable_weight : integer
      • degree_of_obesity : string
    • 400(Json)
      • error_message : string
    • 405(Json)
      • error_message : string

ハンズオン&答え合わせ

今回使用するYAML(エラーになります)

info:
  title: 6/6 TUBサンプル
  description: 6月6日向けのSwaggerサンプルです！
  version: 1.0.0.
host:
basePath: /
schemes:
  - 
swagger: '2.0'
paths:
  /:
    :
      description: '身長と体重を渡すとBMI,適正体重、肥満度を返してくれる'
      produces:
        - application/json
      parameters:
      responses:
        '200':
          description: 成功時
          schema:
            type: object
            properties:
        '400':
          description: パラメータ不足
          schema:
            type: object
            properties:
  /:
    :
      description: '身長と体重を渡すとBMI,適正体重、肥満度を返してくれる'
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
      responses:
        '200':
          description: 成功時
          schema:
            type: object
            properties:
        '400':
          description: パラメータ不足
          schema:
            type: object
            properties:
        '405':
          description: メゾットが存在しない
          schema:
            type: object
            properties:

(おまけ有り)
https://github.com/mht-ryo-chiba/tub_sample

質疑応答

今回のイベントに関してアンケートにご協力お願いします！