【Laravel】l5-swagger でAPI仕様書を簡単に作ろう

Laravel で l5-swagger を使用して簡単にSwaggerのAPI仕様書を作る

l5-swagger

l5-swaggerを使用して簡単にAPI仕様書を作ります。
DarkaOnLine/L5-Swagger

インストール

composer を使用してインストールします。

composer require "darkaonline/l5-swagger"

Swaggerを書く

VSCodeであればこちらのプラグインを使用すると色がついて書きやすいです。
Swagger-PHP Annotation
記法としては Swagger-PHP の記法で書いていきます。

API情報やサーバー情報、共通スキーマは /app/Http/Controllers/Swagger.php を作成して記載するのが良いです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<?php

namespace App\Http\Controllers;

 /**
 * API情報
 * @OA\Info(
 *     title="API Example",
 *     description="Api",
 *     version="1.0.0",
 * )
 *
 * サーバー情報
 * @OA\Server(
 *   description="OpenApi host",
 *   url="http://localhost:8000/api"
 * )
 * 
 * セキュリティスキーマ
 * @OA\SecurityScheme(
 *   securityScheme="BearerAuth",
 *   type="apiKey",
 *   in="header",
 *   name="api_token"
 * )
 * 
 * 作成日
 * @OA\Schema(
 *   schema="created_at",
 *   description="Created At",
 *   type="string",
 *   format="date-time",
 *   example="2017-07-21T17:32:28Z"
 * )
 *
 */
class Swagger
{
}

Getのサンプル

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
class SampleController {
    /**
     * @OA\Get(
     *     path="/api/data.json",
     *     @OA\Response(response="200",　description="The data")
     *     @OA\Response(response=401, description="Unauthorized"),
     *     @OA\Response(response=403, description="Forbidden"),
     *     @OA\Response(response=422, description="Unprocessable Entity"),
     * )
     */
    public function getData() {
        // ...
    }
}

ModelをSchemaとして定義する。
こうすることで Model のスキーマを再利用しやすい状態になります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<?php

namespace App\Models;

/**
 *  @OA\Schema(
 *      schema="User",
 *      type="object",
 *      description="User Model",
 *      @OA\Property(
 *          property="id",
 *          description="ID",
 *          type="integer",
 *          format="int64",
 *          example="1"
 *      ),
 *      @OA\Property(
 *          property="name",
 *          description="Name",
 *          type="integer",
 *          format="int64",
 *          example="1"
 *      )
 * )
 *
 * @package App\Models
 */
class User extends BaseModel
{
}

Postのサンプル。
Loginの書き方として user/login にPOSTして Userスキーマと created_at を組み合わせて返すようになっています。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
class SampleController {
    /**
     *  @OA\Post(
     *      tags={"User"},
     *      path="/user/login",
     *      summary="User Login",
     *      description="User Login",
     *      @OA\RequestBody(
     *          required=true,
     *          @OA\JsonContent(
     *              type="object",
     *              required={"email", "password"},
     *              @OA\Property(
     *                  property="email",
     *                  type="string",
     *                  example="example@example.org",
     *                  description="Email"
     *              ),
     *              @OA\Property(
     *                  property="password",
     *                  type="string",
     *                  example="p@ssw0rd",
     *                  description="Password"
     *             )
     *          ),
     *      ),
     *      @OA\Response(
     *        response=200,
     *        description="OK",
     *        @OA\JsonContent(
     *           @OA\Property(
     *             property="account",
     *             allOf={
     *                 @OA\Schema(ref="#/components/schemas/User"),
     *                 @OA\Schema(
     *                      @OA\Property(
     *                          property="created_at",
     *                          oneOf={@OA\Schema(ref="#/components/schemas/created_at")}
     *                      )
     *                 ),
     *              }
     *          ),
     *        )
     *      ),
     *      @OA\Response(response=401, description="Unauthorized"),
     *      @OA\Response(response=403, description="Forbidden"),
     *      @OA\Response(response=422, description="Unprocessable Entity"),
     *  )
     */
    public function login() {
        // ...
    }
}

API Tokenを付けさせる。
以下を参考として持ってきています。
How can i write this JSON swagger-php below with annotations?

1
2
3
4
5
6
7
8
/**
 *     @OA\SecurityScheme(
 *         securityScheme="bearerAuth",
 *         type="http",
 *         scheme="bearer",
 *         description="Entrer le token JST"
 *     )
 */

1
2
3
4
5
6
7
/**
 * @OA\Get(
 *     path="/api/endpoint",
 *     ...
 *     security={{ "bearerAuth": {} }}
 * )
 */

生成

以下のコマンドでドキュメントが生成されます。
生成場所は storage/api-docs/api-docs.json に生成されます。

php artisan l5-swagger:generate

http://localhost/api/documentation に接続するとSwaggerUIで確認ができます。（URLは自分の環境にあったものに読み替えてください。
VSCodeをお使いでしたら Swagger Viewer でも簡単に確認できます。

以下の設定を入れておくとURLを開くと自動的に生成してくれるようです。

1
L5_SWAGGER_GENERATE_ALWAYS=true

設定

各種設定を行いたい場合は以下のコマンドで設定ファイルが /backend/config/l5-swagger.php 作成されます。
作成された設定の中をいじれば生成場所などが変更可能です。

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

メモ

Swaggerをいじっている時、リアルタイムにエラーが出ないので苦肉の策として以下のように生成コマンドを無限ループさせることによって時間差はありますがにエラーを検知できるようにしました。

1
while true; do php artisan l5-swagger:generate;date;done

参考

DarkaOnLine/L5-Swagger