Swagger OpenAPIでAPI Referenceを書く

こんにちは、@takeokunn です。

yaml と yml の違いってなんだろーと調べたところ Please use “.yaml” when possible. って公式のfaqに書いてあったのでなるべく .yaml を使っていこうと思った今日このごろです。

今回はOpenAPIの実装例について書いていこうと思います。

Dockerで構築

docker-compose.yml はこんな感じ。

version: "3.3"
services:
  swagger-editor:
    image: swaggerapi/swagger-editor
    container_name: "swagger-editor"
    ports:
      - "19881:8080"
  swagger-ui:
    image: swaggerapi/swagger-ui
    container_name: "swagger-ui"
    ports:
      - "19882:8080"
    volumes:
      - ./openapi.yaml:/usr/share/nginx/html/openapi.yaml
    environment:
      API_URL: openapi.yaml
  swagger-api:
    image: stoplight/prism:3
    container_name: "swagger-api"
    ports:
      - "19883:4010"
    command: mock -h 0.0.0.0 /openapi.yaml
    volumes:
      - ./openapi.yaml:/openapi.yaml

swagger-ui や swagger-editor は転がってるコードをそのままペタっと貼り付けました。

以前は danielgtaylor/apisprout を使っていたのですが、どうもOpenAPIの最新の仕様に追いついていなかった(要出典)ので今回は stoplight/prism を使いました。

下のサンプルの get: /colors を試しに叩いてみるとこんな感じ。簡単にmockが作れて良いですね。

~/.g/g/t/.emacs.d (*´ω｀*) < curl "http://localhost:19883/colors" -H "Authorization: Bearer xxx"
{"message":200,"colors":[{"id":1,"name":"赤","created_at":"2002/05/12 20:30:15","updated_at":"2002/05/12 20:30:15"}]}

実際に openapi.yaml を書いてみる

Specifitcation とにらめっこして書けば大体できます。

試しに2つのendpointを作ってみました。

• get: /colors: 色を取得する
• post: /colors: 色を作成する

Bearer token を必要とする場合でも簡単に記述てきてとても良いです。

openapi: 3.0.5
info:
  title: OpenAPIテスト
  version: 1.0.0
  description: OpenAPIテスト
servers:
  - url: http://localhost:3000/api/v1
    description: Local server
  - url: https://staging.test.tokyo/api/v1
    description: Staging server
security:
  - bearerAuth: []
paths:
  /colors:
    get:
      summary: Get colors
      description: 色一覧を取得
      responses:
        200:
          description: 色一覧を返す
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 200
                  colors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ColorModel'
    post:
      summary: Create color
      description: 色を作成
      requestBody:
        content:
          application/json:
            schema:
              required:
                - name
              properties:
                name:
                  type: string
                  example: 赤
      responses:
        201:
          description: 作成した色を返す
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  color:
                    type: object
                    $ref: '#/components/schemas/ColorModel'
        400:
          description: 作成エラー
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Failure
components:
  schemas:
    ColorModel:
      type: object
      properties:
        id:
          type: integer
          example: 1
          description: primary id
        name:
          type: string
          example: 赤
          description: 名前
        created_at:
          type: string
          example: 2002/05/12 20:30:15
          description: 作成日
        updated_at:
          type: string
          example: 2002/05/12 20:30:15
          description: 作成日
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API Key

emacsで快適に openapi.yaml を書く

emacsで快適にyamlを書くためにいくつかpluginを入れました。

openapi-yaml-mode

url: magoyette/openapi-yaml-mode

MELPAで公開されていないが、顧客が欲しかった感じのEmacsLispが書かれているので導入した。completionや簡易的なhighlightなどが入っている。

openapi

;; cask
(depends-on "openapi-yaml-mode" :git "https://github.com/magoyette/openapi-yaml-mode.git")

;; config
(use-package openapi-yaml-mode
  :mode (("\\openapi.yaml$" . openapi-yaml-mode))
  :config
  (setq openapi-yaml-use-yaml-mode-syntax-highlight t))

DarthFennec/highlight-indent-guides

url: DarthFennec/highlight-indent-guides

yaml のインデントを可視化してくれるplugin。以下のようにconfigを書いた。

(use-package highlight-indent-guides
  :diminish
  :hook
  ((prog-mode yaml-mode) . highlight-indent-guides-mode)
  :custom
  (highlight-indent-guides-auto-enabled t)
  (highlight-indent-guides-responsive t)
  (highlight-indent-guides-method 'character))

終わりに

openapi.yaml 職人の方は是非弊社で一緒にyamlをかきましょう!!!

www.wantedly.com