swagger とか openapi の概要をサッと知るための記事

概要

swagger って調べてみたら openapi とか出てきたんだけどみたいな人のための記事です。
やってることはわりと単純なことなので、図解してみればわかりやすいかと思います。

openapi ってなに？

API 定義書の書き方を仕様として定めましょう、っていう流れから生まれたもの。
https://github.com/OAI/OpenAPI-Specification

API 定義ってざっくり言ってますが、公式にも書いてある通り REST API に対応するものです。

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.

swagger ってなによ？

openapi の仕様を書いたり見たりするのに便利なツール群についてる名前。
swagger で使ってた書き方とかが基準になって openapi が策定された、みたいなイメージ。
昔 swagger って呼ばれてたらしーぜ、ってくらいの認識で。

エクセルから yaml へ

swagger-ui とか swagger-editor とか調べると色々出てきますが至極単純化すると↓みたいな。

つまり、このエクセルが

↓

こんな感じの yaml に

openapi-sample.yml

openapi: "3.0.0"
info:
  version: 1.0.0
  title: sample api
  description: sample api definition.
  contact:
    name: sample team
    email: [e-mail]
    url: https://sample.com/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: http://localhost:4011
    description: local mock server. https://github.com/stoplightio/prism
paths:
  /user/{id}:
    get:
      tags:
        - user
      parameters:
        - name: id
          in: path
          description: use information api
          required: true
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: user information response
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/user'
components:
  schemas: 
    user: 
      type: object 
      required: 
        - user_id
      properties:
        user_id: 
          type: integer
          format: int64
          example: 123456
        name:
          type: string
          example: testuser
tags:
  - name: user
    description: ユーザーに関する API

正確に言うと yaml じゃなくて json でもよいです。

ただエクセルのほうが見やすくねぇ？

ただ yaml だとパッと見わかりづらい & 直す場所探しづらいので、これを便利にするためのツールがあります。
これが swagger-ui (見やすくする), swagger-editor (直しやすくする)といったものたちです。他にもそれっぽいツールはいくつもあると思います。

swagger-editor
swagger-editor github
swagger-ui
swagger-ui github

docker で実際に動かす

下記ファイル内にある swagger-server については後述。

openapi-docker-compose.yml

version: "3.7"
services:
  swagger-ui:
    image: swaggerapi/swagger-ui
    environment:
      - SWAGGER_JSON=/openapi-sample.yml #読み込む yaml ファイルを指定
    ports:
      - "88:8080"
    volumes:
      - ./openapi-sample.yml:/openapi-sample.yml #読み込む yaml ファイルをコンテナに送っておく
    networks:
      - openapi

  swagger-server:
    image: stoplight/prism:3
    ports:
      - "4011:4010"
    command: mock -h 0.0.0.0 /openapi-sample.yml
    volumes:
      - ./openapi-sample.yml:/openapi-sample.yml
    networks:
      - openapi

networks:
  openapi:

以下のコマンドでコンテナを立ち上げます。

docker-compose -f openapi-docker-compose.yml up -d

localhost:88 で openapi-sample.yml を指定した swagger-ui が見れるようになります。

yaml に書いたとおりの動作をするサーバーを用意する

↑ の openapi-docker-compose.yml の以下の部分です。
今回使ったのはこちら https://stoplight.io/open-source/prism/

  swagger-server:
    image: stoplight/prism:3
    ports:
      - "4011:4010"
    command: mock -h 0.0.0.0 /openapi-sample.yml
    volumes:
      - ./openapi-sample.yml:/openapi-sample.yml
    networks:
      - openapi

これは何をしてるかというと、下の図の右側、swagger-ui から実際にリクエストを受け付け & レスポンス返却をするサーバーです。

↓の画面右側、Try it out を押して。。。

リクエストパラメータ入力、execute を押すと実際に curl で http リクエストが localhost:4011 (今回用意したサーバー)に投げられていることがわかります。

これでモックサーバーとして用意することもできますね。