首頁 > php框架 > Laravel > 詳細了解Laravel Swagger的使用

詳細了解Laravel Swagger的使用

WBOY
發布: 2022-04-11 20:54:10
轉載
4291 人瀏覽過

這篇文章為大家帶來了關於laravel的相關知識,其中主要介紹了Swagger使用的相關問題,下面一起來看一看基於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"}
     *             )
     *         )
     *     ),
登入後複製

詳細了解Laravel Swagger的使用


詳細了解Laravel Swagger的使用


詳細了解Laravel Swagger的使用

詳細了解Laravel Swagger的使用

詳細了解Laravel Swagger的使用

########################################################。使用結構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
熱門教學
更多>
最新下載
更多>
網站特效
網站源碼
網站素材
前端模板