Swaggerとは

REST API作るときに簡単にドキュメント作れます。
curlで動作確認やコード自動生成も出来る！(強い)

Swagger Editor

以下のサイトで編集できる。
https://editor.swagger.io/

諸事情により、アップロード出来ない場合はdockerもある。
API用のコンテナと一緒に立てるのが良さそう。
swaggerapi/swagger-editor

SwaggerでHello World

swagger: '2.0'
# 説明とか
info:
  description: Sample
  version: 1.0.0
  title: Sample API
# REST APIのURLを書く場所
host: 'localhost:3000'
# 共通の階層を指定する。Swagger的にはv1とかがデフォルト
basePath: /v1
# 基本はhttp通信かhttps通信か両方
schemes:
  - http
  - https

# セキュリティの定義
# Basic認証をかけてます
securityDefinitions:
  basicAuth:
    type: basic

# メインディッシュ
# パスに入ったときのinputとoutputを定義する
paths:
  /user/list:
    get:
      tags:
        - user
      summary: ユーザ情報取得
      security:
        - basicAuth: []
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/result_user_list'
  
  /user/regist:
    post:
      tags:
        - user
      summary: ユーザ情報登録
      security:
        - basicAuth: []
      parameters: 
        - in: body
          name: user
          required: true
          schema:
            $ref: '#/definitions/user_model'
      responses:
        '200':
          description: OK
 
# モデルクラスの定義
# なるべく小さく定義して、$refで再利用すると使いやすい
definitions:
  user_model:
    type: object
    properties:
      id:
        type: integer
        example: 10001
      name:
        type: string
        example: okkun
      email:
        type: string
        example: okkun.development@gmail.com
      age:
        type: integer
        example: 24
  
  result_user_list:
    type: object
    properties:
      users:
        type: array
        items:
          $ref: '#/definitions/user_model'
      
    
externalDocs:
  description: Find out more about Swagger
  url: 'http://swagger.io'

結果

こんな感じでユーザ情報一覧を取ってくるAPIドキュメントが作れました。
（プライバシーポリシーどうなってんだ）

swagger-codegenとか使うとyamlを読み取って通信周りのコード自動生成してくれます
https://github.com/swagger-api/swagger-codegen

感想

ドキュメント作るの大事