laravelにswaggerを導入してAPIの仕様書作成とテストをする

swaggerとは

swaggerはRESTなAPIの
・仕様書を作成。
・テストを実行。
ができます。

laravelにswaggerインストール

コマンドプロンプト

composer require "darkaonline/l5-swagger"

jsonではなくyamlで扱いたいので.envに以下を追加。

.env

L5_FORMAT_TO_USE_FOR_DOCS = yaml

swaggerでAPIの仕様書を表示

/api/documentation　にアクセスするとswaggerの表示を確認できます。
このようにシンプルな画面でAPIの仕様書を確認できます。

\storage\api-docs\api-docs.yaml
の内容が表示されます。

swaggerのyamlファイルの書き方

（オンラインエディタを使っても便利 https://editor-next.swagger.io/）
\storage\api-docs\api-docs.yaml
の内容を編集していきます。

yaml

openapi: 3.0.0
info:
  title: H1タイトル #H1
servers:
  - url: http://localhost/api/ #url
    description: ローカル開発環境 #urlのdescription
paths:
  /test: #パス
    get: #メソッド
      summary: H2タイトル #H2
      parameters: #get情報
      - name: page
        in: query # getで渡される
        # in: path # urlに埋め込まれる
        # required: true
        schema:
          type: integer
          # type: boolean
          # type: array
          # type: object
      requestBody: #post情報
        # required: true #必須
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "なまえ"
                description:
                  type: string
                  example: "詳細"
      responses: #レスポンス
        '200': #200が返ってきたら
          description: OK
          content:
            application/json: #返ってきたデータをjsonとして表示
              schema:
                $ref: '#/components/schemas/testsResponse' # ★が表示される
        '404':
          description: not found
        '500':
          description: サーバーエラー
#   post: #メソッド
#     summary: H2タイトル #H2
#     .....
#
# /test2:
#   get:
#   .....

components:
  schemas:
    testsResponse: # ★ここ
      type: object
      properties:
        data:
          type: object
          properties: # この形式で返ってくるよ。
            id:
              type: integer
              format: int
              example: 1
            name:
              type: string
              example: わたしの名前

swaggerでAPIのテスト

APIのテストは
「Try it out」をクリック

「Execute」をクリック

これでAPIの実行結果が表示されます。

このようにAPIの仕様書を見やすくまとめてテストまで出来るswagger。
是非活用してみてください。