こんにちは、@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などが入っている。
;; 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をかきましょう!!!