這篇“Laravel Swagger怎么使用”文章的知識(shí)點(diǎn)大部分人都不太理解，所以小編給大家總結(jié)了以下內(nèi)容，內(nèi)容詳細(xì)，步驟清晰，具有一定的借鑒價(jià)值，希望大家閱讀完這篇文章能有所收獲，下面我們一起來(lái)看看這篇“Laravel Swagger怎么使用”文章吧。
成都創(chuàng)新互聯(lián)公司網(wǎng)絡(luò)公司擁有10多年的成都網(wǎng)站開(kāi)發(fā)建設(shè)經(jīng)驗(yàn)，上千客戶的共同信賴。提供網(wǎng)站制作、網(wǎng)站設(shè)計(jì)、網(wǎng)站開(kāi)發(fā)、網(wǎng)站定制、友情鏈接、建網(wǎng)站、網(wǎng)站搭建、響應(yīng)式網(wǎng)站、網(wǎng)頁(yè)設(shè)計(jì)師打造企業(yè)風(fēng)格，提供周到的售前咨詢和貼心的售后服務(wù)
本教程是基于Laravel 生成swagger 為例子，其實(shí)這個(gè)東西和語(yǔ)言或者和框架基本沒(méi)啥區(qū)別，因?yàn)槎际怯玫墓玫膉son ，通過(guò)程序掃描swagger預(yù)先規(guī)定的“語(yǔ)言”，生成結(jié)構(gòu)存入json中，通過(guò) swagger ui 展現(xiàn)出來(lái)（或者自己開(kāi)發(fā)）。
對(duì)于php開(kāi)發(fā)人員來(lái)說(shuō)，有大部分同學(xué)很不喜歡swagger。 因?yàn)檫@個(gè)看上去寫起來(lái)好麻煩啊，一想到分分鐘用php寫完的代碼，寫swagger要寫10分鐘，心里就抵觸這個(gè)東西。
身邊有Java開(kāi)發(fā)的同學(xué)就知道他們很大一部分都用swagger，因?yàn)閖ava要維護(hù)數(shù)據(jù)結(jié)構(gòu)，而且swagger在java整合得更靈活。
這個(gè)時(shí)候java如果看到有php 說(shuō)swagger反人類的東西，太麻煩了，上古時(shí)代的產(chǎn)物。那身邊的java朋友會(huì)心里竊喜，這么好用的東西都不用，還說(shuō)php是世界上最好的語(yǔ)言。
最近在寫自動(dòng)生成代碼，其實(shí)現(xiàn)在Laravel 很多自動(dòng)生成CURD的。比如像laravel-admin ，一條命令生成CURD，但是生成之后，數(shù)據(jù)看上去很冷。 比如有一些字段不需要顯示，有一些是要select關(guān)聯(lián)枚舉的，有一些是 hasMany的，還有 overtrue（正超）的api腳手架也挺好的
所以swaager也可以根據(jù)業(yè)務(wù)需求寫自動(dòng)化生成
composer require "darkaonline/l5-swagger"
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider" php artisan l5-swagger:generate
填寫下面例子生成之后再訪問(wèn)
/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" * ) * ) */
如果要匹配path中的數(shù)值則 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={
* {
* "oauth3_security_example": {"write:projects", "read:projects"}
* }
* },
* )
*/
/**
* @OA\Post(
* path="/api/test/store",
* operationId="api/test/store",
* tags={"Test"},
* summary="Test創(chuàng)建",
* description="Test提交創(chuàng)建",
* @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="狀態(tài)",
* required=true,
* explode=true,
* @OA\Schema(
* type="array",
* default="available",
* @OA\Items(
* type="string",
* enum = {"available", "pending", "sold"},
* )
* )
* ), * @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"}
* )
* )
* ),* @OA\RequestBody( * description="order placed for purchasing th pet", * required=true, * @OA\JsonContent(ref="#/components/schemas/UserModel") * ),
/**
* @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,
* )
* )
*/一個(gè)枚舉單獨(dú)創(chuàng)建一個(gè)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" * ),
這樣前端開(kāi)發(fā)者就可以
和枚舉差不多，通過(guò)一個(gè)Property關(guān)聯(lián)模型
* @OA\Property( * property="user_detail", * ref="#/components/schemas/UserModel2" * ),
關(guān)聯(lián)模型和枚舉，可以自動(dòng)生成請(qǐng)求的參數(shù)和，返回的結(jié)構(gòu)
* @OA\Response( * response=200, * description="successful operation", * @OA\JsonContent( * type="array", * @OA\Items(ref="#/components/schemas/UserModel"), * @OA\Items(ref="#/components/schemas/UserModel2") * ) * ),
就比如那天前端小妹跟你說(shuō)，哥哥，支付狀態(tài)3代表什么，可能你很快的說(shuō)出了是某某狀態(tài)，但是問(wèn)你11是啥狀態(tài)，人都要沙雕了。
通過(guò)swagger 的Schema 能讓前端人員摸清后端的結(jié)構(gòu)信息
/**
* @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,
* ),
* )
* }
* )
*//** * @OA\SecurityScheme( * type="apiKey", * in="query", * securityScheme="api_key", * name="api_key" * ) */
在接口中添加
security={{"api_key": {}}},這時(shí)，swagger Ui 會(huì)出現(xiàn)一個(gè)鎖一樣的東西
可以輸入自己的token，請(qǐng)求的時(shí)候會(huì)帶上token
線上環(huán)境如果訪問(wèn)不了，可能是你nginx 配置的問(wèn)題，因?yàn)?，laravel-swagger 是通過(guò)file_content_get() 的方式 echo 輸出js 的。而你的nginx 配置判斷，如果是 .js 或者css 是靜態(tài)文件，所以到不了index.php ，更執(zhí)行不了 file_content_get 函數(shù)了。可以參考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 這個(gè)換成你自己的;
try_files $uri =404;
}以上就是關(guān)于“Laravel Swagger怎么使用”這篇文章的內(nèi)容，相信大家都有了一定的了解，希望小編分享的內(nèi)容對(duì)大家有幫助，若想了解更多相關(guān)的知識(shí)內(nèi)容，請(qǐng)關(guān)注創(chuàng)新互聯(lián)行業(yè)資訊頻道。
