# laravel 安裝 swagger

## 官方 git

https://github.com/DarkaOnLine/L5-Swagger

## 安裝 L5-Swagger 套件

composer require "darkaonline/l5-swagger"

## 發布 L5-Swagger 配置文件

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

## 配置 Swagger
可以打開 config/l5-swagger.php 目錄，根據需要的内容進行配置。你可以設置 API 文檔的基本信息，如標題、版本等。

## 生成 Swagger 文檔

php artisan l5-swagger:generate

php artisan l5-swagger:generate system_api_docs

# 使用方式
## 在 Controllers 中添加 Swagger 註釋
首先，您需要在控制器中添加 Swagger 註釋。這些註釋將用於生成 API 文檔。
例如，在 `app/Http/Controllers/UserController.php` 中：

/**
 * @OA\Info(
 *     title="我的 API 文檔",
 *     version="1.0.0",
 *     description="這是一個示例 API 文檔"
 * )
 */
class UserController extends Controller
{
    /**
     * @OA\Get(
     *     path="/api/users",
     *     summary="獲取所有用戶",
     *     @OA\Response(response="200", description="成功獲取用戶列表")
     * )
     */
    public function index()
    {
        // 方法實現
    }

    /**
     * @OA\Post(
     *     path="/api/users",
     *     summary="創建新用戶",
     *     @OA\RequestBody(
     *         @OA\JsonContent(
     *             @OA\Property(property="name", type="string"),
     *             @OA\Property(property="email", type="string")
     *         )
     *     ),
     *     @OA\Response(response="201", description="用戶創建成功")
     * )
     */
    public function store(Request $request)
    {
        // 方法實現
    }
}

這裡的註釋說明：
* @OA\Info: 定義 API 文檔的基本信息。
* @OA\Get 和 @OA\Post: 定義 HTTP 方法和路徑。
* @OA\Response: 描述可能的響應。
* @OA\RequestBody: 描述請求體的結構。

## 在路由文件中添加 Swagger UI 路由
在 routes/web.php 或 routes/api.php 中添加以下路由：
:::warning
新版的 Swagger 可以不用添加，經過在 laravel 11 測試可以不加進行訪問
:::

Route::get('/api/documentation', '\L5Swagger\Http\Controllers\SwaggerController@api')->name('l5swagger.api');

這將創建一個訪問 Swagger UI 的路由。

# 配置 Swagger UI

## 在 config/l5-swagger.php 文件中，您可以進行更多自定義配置

'routes' => [
    'api' => 'api/documentation',
],

'paths' => [
    'docs_json' => 'api-docs.json',
    'docs_yaml' => 'api-docs.yaml',
    'annotations' => [
        base_path('app'),
    ],
],

'generate_always' => env('L5_SWAGGER_GENERATE_ALWAYS', false),

這些配置的含義：
* routes.api: 設置 Swagger UI 的訪問路徑。
* paths.docs_json 和 paths.docs_yaml: 設置生成的文檔文件名。
* paths.annotations: 指定要掃描的目錄以查找 Swagger 註釋。
* generate_always: 設置是否在每次請求時重新生成文檔。

# 生成 API 文檔
每次更新 API 註釋後，您需要重新生成文檔：

php artisan l5-swagger:generate

or
可以在 env 添加自動生成文檔

L5_SWAGGER_GENERATE_ALWAYS=true # 是否自動生成 Swagger文檔

# 訪問 Swagger UI

完成以上步驟後，您可以通過訪問 http://your-app-url/api/documentation 來查看生成的 API 文檔。

最佳實踐

* 保持文檔更新：每次修改 API 時，都要更新相應的 Swagger 註釋。
* 使用模型定義：對於複雜的數據結構，可以使用 `@OA\Schema` 來定義模型。
* 分組 API：使用 `@OA\Tag` 來組織和分類您的 API。
* 添加授權信息：如果您的 API 需要認證，可以使用 `@OA\SecurityScheme` 來定義認證方式。
* 使用環境變量：將一些配置項（如基礎 URL）設置為環境變量，以便在不同環境中靈活使用。

# 呈現