詳細了解Laravel Swagger的使用
- WBOY轉載
- 2022-04-11 19:04:144247瀏覽
這篇文章為大家帶來了關於laravel的相關知識，其中主要介紹了Swagger使用的相關問題，下面一起來看一看基於Laravel 生成swagger 為例子，希望對大家有幫助。
【相關推薦：laravel影片教學】
swagger太辣雞了？
本教學是基於Laravel 產生swagger 為例子，其實這個東西和語言或和框架基本上沒啥區別，因為都是用的公用的json ，透過程式掃描swagger預先規定的「語言”，生成結構存入json中，透過swagger ui 展現出來（或自己發展）。
對於php開發人員來說，有大部分同學很不喜歡swagger。因為這個看上去寫起來好麻煩啊，一想到分分鐘用php寫完的程式碼，寫swagger要寫10分鐘，心裡就抵觸這個東西。
身邊有Java開發的同學就知道他們很大一部分都用swagger，因為java要維護資料結構，而且swagger在java整合得更靈活。
這時候java如果看到有php 說swagger反人類的東西，太麻煩了，上古時代的產物。那身邊的java朋友會心裡竊喜，這麼好用的東西都不用，還說php是全世界最好的語言。
我為啥用swagger
最近在寫自動產生程式碼，其實現在Laravel 很多自動產生CURD的。例如像laravel-admin ，一指令產生CURD，但產生之後，資料看起來很冷。例如有一些欄位不需要顯示，有些是想要select關聯枚舉的，有些是hasMany的，還有overtrue（正超）的api腳手架也挺好的
所以swaager也可以依照業務需求寫自動化產生
L5-Swagger
#https://github.com/DarkaOnLine/L5-Swagger
安裝：
composer require "darkaonline/l5-swagger"
使用：
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider" php artisan l5-swagger:generate
填寫下面範例生成之後再造訪
/api/documentation
@OA\Info 為必須
範例
/** * @OA\Info( * version="1.0.0", * title="L5 OpenApi", * description="L5 Swagger OpenApi description", * @OA\Contact( * email="darius@matulionis.lt" * ), * @OA\License( * name="Apache 2.0", * url="http://www.apache.org/licenses/LICENSE-2.0.html" * ) * ) */
get 請求
如果要符合path中的數值則in path 查詢in query
/**
* @OA\Get(
* path="/projects/{id}",
* operationId="getProjectById",
* tags={"Projects"},
* summary="Get project information",
* description="Returns project data",
* @OA\Parameter(
* name="id",
* description="Project id",
* required=true,
* in="path",
* @OA\Schema(
* type="integer"
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation"
* ),
* @OA\Response(response=400, description="Bad request"),
* @OA\Response(response=404, description="Resource Not Found"),
* security={
* {
* "oauth2_security_example": {"write:projects", "read:projects"}
* }
* },
* )
*/
POST 請求
/**
* @OA\Post(
* path="/api/test/store",
* operationId="api/test/store",
* tags={"Test"},
* summary="Test创建",
* description="Test提交创建",
* @OA\Parameter(
* name="id",
* description="",
* required=false,
* in="query",
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(
* ref="#/components/schemas/Test"
* )
* ),
* @OA\Response(response=400, description="Bad request"),
* @OA\Response(response=404, description="Resource Not Found"),
* security={
* {
* "api_key":{}
* }
* },
* )
*/
檔案上傳參數
* @OA\RequestBody( * @OA\MediaType( * mediaType="multipart/form-data", * @OA\Schema( * type="object", * @OA\Property( * property="file", * type="file", * ), * ), * ) * ),
傳入為枚舉
* @OA\Parameter(
* name="status",
* in="query",
* description="状态",
* required=true,
* explode=true,
* @OA\Schema(
* type="array",
* default="available",
* @OA\Items(
* type="string",
* enum = {"available", "pending", "sold"},
* )
* )
* ),
Body 為Json 方式提交
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(
* @OA\Property(
* property="id",
* type="string"
* ),
* @OA\Property(
* property="name",
* type="string"
* ),
* example={"id": 10, "name": "Jessica Smith"}
* )
* )
* ),
########################################################。使用結構Schema作為請求參數###
* @OA\RequestBody( * description="order placed for purchasing th pet", * required=true, * @OA\JsonContent(ref="#/components/schemas/UserModel") * ),###Schema的使用###
/**
* @OA\Schema(
* schema="UserModel",
* required={"username", "age"},
* @OA\Property(
* property="username",
* format="string",
* description="用户名称",
* example="小廖",
* ),
* @OA\Property(
* property="age",
* format="int",
* description="年龄",
* example=1,
* nullable=true,
* )
* )
*/###枚舉######一個枚舉單獨建立一個Schema###/**
* @OA\Schema(
* schema="product_status",
* type="string",
* description="The status of a product",
* enum={"available", "discontinued"},
* default="available"
* )
*/###映射到模型中的具體字段###* @OA\Property( * property="status", * ref="#/components/schemas/product_status" * ),###這樣前端開發者就可以######關聯模型#######和枚舉差不多，透過一個Property關聯模型###
* @OA\Property( * property="user_detail", * ref="#/components/schemas/UserModel2" * ),###關聯模型和枚舉，可以自動產生請求的參數和，返回的結構############返回為模型結構###
* @OA\Response( * response=200, * description="successful operation", * @OA\JsonContent( * type="array", * @OA\Items(ref="#/components/schemas/UserModel"), * @OA\Items(ref="#/components/schemas/UserModel2") * ) * ),###就例如那天前端小妹跟你說，哥哥，支付狀態3代表什麼，可能你很快的說出了是某某狀態，但是問你11是啥狀態，人都要沙雕了。 ### 透過swagger 的Schema 能讓前端人員摸清後端的結構訊息，例如：###############各位，這些都可以自動化編程，自動產生的，工作效率不要太爽######多個合併Schema###
/**
* @OA\Schema(
* schema="UserModel",
* allOf={
* @OA\Schema(ref="#/components/schemas/UserModel2"),
* @OA\Schema(
* type="object",
* description="Represents an authenticated user",
* required={
* "email",
* "role",
* },
* additionalProperties=false,
* @OA\Property(
* property="email",
* type="string",
* example="user@example.com",
* nullable=true,
* ),
* )
* }
* )
*/###驗證提供outh2 和apikey 兩種方式，在存放全域設定中寫入（也可以任意目錄中）###/** * @OA\SecurityScheme( * type="apiKey", * in="query", * securityScheme="api_key", * name="api_key" * ) */###在介面中加入###
security={{"api_key": {}}},###這時，swagger Ui 會出現一個鎖一樣的東西###############可以輸入自己的token，請求的時候會帶上token ############ 可以結合Laravel 的自帶token驗證，可以參考之前寫的文章Laravel guard 菊花守衛者######更多使用方法可以查看官網範例： https:/ /github.com/zircote/swagger-php/tree/master/Examples/petstore-3.0#########可能遇到的問題########線上環境如果訪問不了，可能是你nginx 設定的問題，因為，laravel-swagger 是透過file_content_get() 的方式echo 輸出js 的。而你的nginx 配置判斷，如果是 .js 或css 是靜態文件，所以到不了index.php ，更執行不了 file_content_get 函數了。可以參考nginx 設定:###charset utf-8;
client_max_body_size 128M;
location / {
try_files $uri $uri/ /index.php$is_args$args;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass php74:9000 这个换成你自己的;
try_files $uri =404;
}###【相關推薦：###laravel影片教學###】###以上是詳細了解Laravel Swagger的使用的詳細內容。更多資訊請關注PHP中文網其他相關文章！
陳述：
本文轉載於：csdn.net。如有侵權，請聯絡admin@php.cn刪除