# Swaggerについて
## Swaggerとは
Swaggerは、RESTful APIを構築するためのオープンソースフレームワークである。
Open API Initiativeが策定した標準フォーマットで、ドキュメント生成やリクエスト送信が行える。

## Swaggerの各種ツール
### Swagger Spec
Swaggerの書式で記述した仕様書。JSON形式orYAML形式で記述する。
### Swagger Editor
Swagger Specファイルの生成・編集を行うツール。ブラウザ上で動き、リアルタイムにドキュメントが更新されるため構文チェックが行える。また、APIの実行も可能である。
### Swagger UI
Swagger Specを読み込み、HTML形式ドキュメントに変換するツール。
### Swagger Codegen
Swagger Specで記載された設計から、APIのスタブを自動的に作成するツール。

## Swaggerの仕様書を読んでみよう
### 今回読む仕様書
SwaggerEditorに標準装備されているサンプル仕様書。
### YAML形式の書式
YAML(YAML Ain't Markup Language)は、構造化されたデータを表現するためのフォーマットである。
各種設定ファイルやログファイル等に用いられる。
XMLと比較すると、非常にシンプルで理解がしやすい。
#### YAML形式のデータ表現
* 配列
**行頭「-」** で表現。半角スペースでインデントするとネスト表現ができる。
* ハッシュ
**キー：値**で表現。同様にネストが可能で、配とハッシュの相互ネストが可能である。
* スカラー
配列・ハッシュ以外のデータ。（数値や文字列など）
数値やnull値、日付などは自動的に形式が判別される。
文字列は""('')で囲むことで認識される。

### サンプル仕様書を解析する

#### ヘッダ部分

swagger: "2.0"
info: 
  description: "This is a sample server…（仕様書の概略文）"
  version: "1.0.0（仕様書のバージョン）"
  title: "Swagger Petstore（仕様書のタイトル）"
  termsOfService: "http://swagger.io/terms/（サービスの利用条件を記述）"
  contact:
    email: "（仕様書著者の連絡先⇒eメールアドレス）"
  licence:　
    name: "Apache 2.0"
    url:　"（↑仕様書で必要なライセンス名、←ライセンスURL）"
host: "（ホスト名）"
basePath: "/v2"

* swagger：swaggerのバージョン。
* info：仕様書のタイトル及び概略文、連絡先、ライセンス情報等を記述。
* host：ホスト名
* basePath：APIの基準となるパス名

#### タグ部分

tags:
- name: "pet（タグ名。以下配列）"
  description: "（タグの説明文）"
  externalDocs:
    description: "（詳細説明リンクの説明）"
    url: "（詳細説明リンクのURL）"
schemes:
- "https"
- "http"    

* tags：各処理を区別するためのタグ名及び詳細説明を記述。
* schemes：利用する通信プロトコルの選択肢を記述。

#### パス部分

paths:
  /pet:
    post:
      tags:
      - "pet"
      summary: "（処理の概略文）"
      description: ""
      oparationId: "addPet"
      consumes: "（入力のコンテントタイプ指定）"
      produces: "（出力のコンテントタイプ指定）"
      paramaters: 
      － in: "body（ボディ部分に記述）"
         name: "body"
         description: "（パラメータの説明 必須か否か↓）"
         required: true
         schema:
           $ref: "#/definitions/Pet（パスの変化指定）"
      responses:
        "405":
          description: "Invalid input（エラーメッセージ）"
      security:
      - petstore_auth:
        - "write:pets（書き込み権限者指定）"
        - "read:pets（読み取り権限者指定）"    

* paths：URLのパス名（/pet等）に応じて、行う処理を記述する。（リクエストマッピングのイメージ）
* post：処理に利用するHTTPリクエスト。（他にget, put, delete等）
* paramaters:パラメータについての情報。
* responses:HTTPレスポンスについての記述。
* security:読み取り・書き込み権限の設定。

#### 定義部分

securityDefinitions:
  petstore_auth:
    type: "oauth2"
    authorizationUrl: "（認証URL）"
    flow: "implicit"
    scopes:
      write:pets: "modify pet in your account"
      read:pets: "read your pets（権限のスコープ設定）"
　api_key:
    type: "apiKey"
    name: "api_key"
    in: "header（ヘッダ部分に記述）"
definitions:
  Order:
    type: "Object"
    properties:
      id:
        type: "integer"
        format: "int64"
      petId:
        type: "integer"
        format: "int64" 

* securityDefinitions：セキュリティに関する定義
　　* petStore_auth：認証方式・認証URL・権限のスコープ等を記述
　　* api_key：APIの鍵設定
* definitions：各変数の型定義
　　* Order：オブジェクトの型定義。typeはObjectとなる。
　　* Properties：オブジェクトが持つ要素。
　　　　* type:要素の型定義。
　　　　* required:必須の要素名
　　　　* format:要素のフォーマット指定。
　　　　* xml:XML指定。nameとwrapped(boolean)の2つの子要素を持つ。

## フロント・バック分離の観点から見たSwagger
Swaggerは、API仕様書を記述するフォーマットでありつつ、その場で仮のモックサーバとしてAPIを動かすことができるのが最大のメリットである。
ただ仕様書を書くだけでなく、実際に動かせるため、APIで必要な振る舞いの確認や、フロントエンド側で与えるべきパラメータや返り値の確認が容易になる。
また、フロントエンド側、バックエンド側の両方の開発部門でSwaggerの設計書を共有することで、両者の齟齬が無くなり共通したシステムイメージを持って仕事に取り掛かれる。
ゆえに、Swaggerはフロントエンド側、バックエンド側の両者の優れた橋渡し役として活用することで、より正確で効率の良いシステム開発に繋がる。

###### tags: `アジャイルプラクティス`