Laravel & VSCodeによるAPI仕様書管理の一案

今回の記事は、LaravelでAPI開発をすると同時に、
VSCodeの拡張機能を用いてAPI仕様書の管理もしてしまおうという狭い話です。

まずLaravel。
ひとまず最新の6を使うこととします。
今回の主題はAPI実装よりもAPIの仕様管理ということで、
マークダウンでAPIの仕様を記述します。
場所はresources/apiを作るなどして保存しましょう。

api_template.md

# API

API説明

# エンドポイント

## パス

### /api/hoges/{id}

## HTTPメソッド

### GET

# リクエスト

| パラメータ名 | データ型 | 必須  | 制約 | 説明 |
| ------------ | -------- | :---: | ---- | ---- |
| id           | integer  |  ⭕️   |      | ID   |

# レスポンス

## 200 取得成功

``json
{
  "id": 1,
  "name": "Hoge",
  "foos": [
    {
      "id": 1,
      "hoge_id": 1,
    },
    {
      "id": 2,
      "hoge_id": 1,
    }
  ]
}
``

## 500 エラー

---

[戻る](/api_docs)

APIを使う際に必要な情報を記述します。
ちなみにVSCodeはマークダウンを編集しながらプレビューも見られるので便利です。

ただし、ブラウザで見る際はHTMLに変換したほうがわかりやすい。
そこでVSCodeの拡張機能「Markdown All in One」が役に立ちます。

この拡張機能をインストールしてHTML出力のコマンドを実行すると、同じディレクトリresources/apiにHTMLファイルが出力されます。

そのHTMLファイルをLaravelのルーティングで読み込んで表示しようというのが、本記事の肝です。

routes/web.php

<?php

Route::get('api_docs/{name?}', function ($name = 'index') {
    if (config('app.env') === 'production') {
        return abort(404);
    }
    $path = resource_path() . '/api/' . $name . '.html';
    if (file_exists($path)) {
        return file_get_contents($path);
    } else {
        return abort(404);
    }
});

一応本番環境では表示しないようにしています。
このルーティングで、例えば/api_docs/api_templateとアクセスすることでAPIの仕様を表示できます。

これによって、ひとつのLaravelリポジトリでAPIの実装と仕様管理の両方ができるのは便利ではないかと思っています