前言

使用 Swagger 讓 API 開發有文件化與測試功能
本教學為記錄建置專案過程作為未來再次建置的參考

建置 Laravel 專案

本次建置的框架版本為 Laravel 10，PHP 版本為 8.1

安裝 PHP

[[install_ubuntu_php_8]]

安裝 Composer

[[install_ubuntu_composer]]

安裝 Laravel 安裝器

composer global require laravel/installer

建立 Laravel 專案

laravel new example-app

參考官方教學
Your First Laravel Project

導入套件 Swagger-UI

介紹套件 L5-Swagger

本次要使用的套件為 L5-Swagger，這是一個整合 Laravel 與 Swagger UI 的套件，
因為底層是基於 swagger-php 這個專案，原理是透過特定的 PHP 註解寫法自動產生 Swagger UI 可以辨識的語法。
之所以是 L5 是因為最初是為了 Laravel 5 的套件，但目前已經支援 Laravel 10 了。

安裝套件 L5-Swagger

安裝指令要根據目前的框架版本來調整，如果是最新的版本就能不指定版本號直接安裝。

composer require "darkaonline/l5-swagger"

詳細的安裝教學或其他版本的設定需要參閱官方安裝教學：Installation

初次設定

執行指令將 L5-Swagger 的設定和畫面檔案加入專案內

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

執行之後會多出下面兩個檔案

• 全域設定：laravel-project/config/l5-swagger.php
• 專案畫面：laravel-project/resources/views/vendor/l5-swagger

文件建立

php artisan l5-swagger:generate

初次執行會出現類似下方的錯誤
![[laravel_swagger_ui_1.jpg]]
這是因為沒有在 Controllers 加上 OA 規範，詳細可參考 Required @OA\Info() not found
以下為參考範例

<?php

namespace App\Http\Controllers;

use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Routing\Controller as BaseController;
use OpenApi\Attributes as OA;

/**
 * @OA\Info(
 *      version="1.0.0",
 *      x={
 *          "logo": {
 *              "url": "https://via.placeholder.com/190x90.png?text=L5-Swagger"
 *          }
 *      },
 *      title="L5 OpenApi",
 *      description="L5 Swagger OpenApi description",
 *      @OA\Contact(
 *          email="darius@matulionis.lt"
 *      ),
 *     @OA\License(
 *         name="Apache 2.0",
 *         url="https://www.apache.org/licenses/LICENSE-2.0.html"
 *     )
 * )
 *  @OA\PathItem(
 *      path="/"
 * )
 * @OA\server(
 *      url=L5_SWAGGER_CONST_HOST,
 *      description="Localhost"
 * )
 *
 */

class Controller extends BaseController
{
    use AuthorizesRequests, ValidatesRequests;
}

進入測試畫面

Swagger UI 的設定在 config/l5-swagger.php
查看 routes 可得知 Swagger UI 預設的文件路由是 api/documentation
打入網址就會出現一個空的 Swagger UI 畫面，到這邊就算是導入套件完成。

進階使用 L5-Swagger

自動建立說明文件

由於每次改動程式都要下指令才會產生新的文件

php artisan l5-swagger:generate

因此官方建議可以透過環境設定來改為自動產生 Swagger/OpenApi annotations and generating documentation
在 laravel-project/.env 內 加入 L5_SWAGGER_GENERATE_ALWAYS=true

標準語法產生工具

VScode extension: Swagger-PHP Annotation  可自動生成標準語法，節省時間。

註解格式用法參考

可參考此手冊
https://zircote.github.io/swagger-php/reference/annotations.html