はじめに

現在、本業で所属している会社がドキュメント化の文化がなかったので、ドキュメント整備の観点からSwaggerを導入してみました。

Swaggerとは

概要

まず「Swaggerとは何か？」
OpenAPIというRESTful APIのフォーマットがあり、そのフォーマットに沿って記述されたAPIを閲覧、実行などができるツールセットになります。
簡単なフォーマットを書くだけで、RESTful APIを表現できるイカしたやつだと思って頂ければ結構です。
https://swagger.io/
その中でも今回はSwagger UIとSwagger Editorを使用します。

Swagger UI

Open APIから情報を読み取って、HTMLとしてAPIを整形してくれるツール。
エンドポイントやパラメーターやレスポンスを見やすく整形してくれる。

Swagger Editor

Open APIのエディタとビューアーが一体になっている編集ツール。
変更がリアルタイムに反映されるので楽に編集作業を行える。

実装

今回はサクッと導入したいのでDockerで立ち上げていきます。
それでは早速やっていきましょう！

Swagger UI

Swagger UI の起動設定

まずはdocker-composeの設定。
※8080ポートはフロントのポートで使用しているので8081に割り当てています。ここはお好みで。

version: "3"

services:
  swagger-ui:
    image: swaggerapi/swagger-ui
    container_name: "swagger-ui"
    ports:
      - "8081:8080"
    volumes:
      - ./api/openapi.yml:/openapi.yml
    environment:
      SWAGGER_JSON: /openapi.yml

お次にAPIを記述していくファイルの作成。
docker-composeでバインドさせるopenapi.ymlというファイルを作成します。
※一旦は最小限の状態で作成

openapi: 3.0.0

設定ファイルを作ったらDockerを起動します。

$ docker-compose up -d

起動できたらlocalhost:8081にアクセスしてみます。
下記の画面表示されればOK！

OpenAPI を書いてみる

起動が出来たら実際にAPIを書いてみます。

openapi: 3.0.0
# ドキュメントの説明
info:
  version: 1.0.0
  # ドキュメントタイトル
  title: Swaggerテスト
  # ドキュメントの説明
  description: Swaggerをお試しで使ってみるよ
# エンドポイントルート
servers:
  - url: "http://localhost:3000/api/v1"
paths:
  # APIエンドポイント: http://localhost:3000/api/v1/test
  /test:
    # リクエストメソッド
    get:
      summary: GET test
      description: テストAPI
      operationId: getTest
      responses:
        200:
          description: レスポンスサンプル
          content:
            application/json:
              # レスポンスデータ
              schema:
                type: object
                properties:
                  hoge:
                    type: string
                    example: hoge
                  fuga:
                    type: string
                    example: fuga

# ドキュメントリンク
externalDocs:
  description: Swagger公式
  url: http://swagger.io

ブラウザをリロードするとこんな感じ

エンドポイントやレスポンスがうまい具合に表現されてればOK！

Swagger Editor

お次はSwagger Editorを導入します。
※こちらはポートを8082にしていますがお好みで。

version: "3"

services:
  swagger-ui:
    image: swaggerapi/swagger-ui
    container_name: "swagger-ui"
    ports:
      - "8081:8080"
    volumes:
      - ./api/openapi.yml:/openapi.yml
    environment:
      SWAGGER_JSON: /openapi.yml

  # ~~ 以下追加 ~~
  swagger-editor:
    image: swaggerapi/swagger-editor
    container_name: "swagger-editor"
    ports:
      - "8082:8080"

docker起動。

$ docker-compose up -d

localhost:8082でアクセスして下記が表示されればOK！

デフォルトが上記の画面ですが、実際に左のエディタで編集することで、右のビューアーで確認することが可能です。

さいごに

この記事ではSwagger UI / Swagger Editorの起動をサクッとやってみました！
マークダウンで書かれているドキュメントに比べて圧倒的に見やすいですね！
curlコマンドの生成もやってくれるので実際にコールすることも可能！使いやすい！
次回の記事ではOpenAPIの記述フォーマットや実際に使うケースについてまとめようと思います！
以上。最後までご覧くださりありがとうございます！