This post is Private. Only a writer or those who know its URL can access this post.

Article information
Show article in Markdown
Report article
Help us understand the problem. What is going on with this article?

TUB-online サーバーサイドエンジニアから学ぶ"Swagger入門"

本イベントの流れ

  • このイベントで得られること
  • 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

https://us-central1-tub-89275.cloudfunctions.net/getHealthcare?weight=52&height=170

  • /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

ハンズオン&答え合わせ

https://editor.swagger.io/

今回使用する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

質疑応答

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

https://forms.gle/Z96J8AuzkR6BKSG29

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした