php-swagger 3.0版本

laravel_lzs發表於2020-12-15
PHPSwagger

請求方式

@OA\Get()

  /**
     * @OA\Get(path="/user/logout",
     *   tags={"user"},
     *   summary="Logs out current logged in user session",
     *   description="",
     *   operationId="logoutUser",
     *   parameters={},
     *   @OA\Response(response="default", description="successful operation")
     * )
     */

@OA\Post()

 /**
     * @OA\Post(path="/user",
     *   tags={"user"},
     *   summary="Create user",
     *   description="This can only be done by the logged in user.",
     *   operationId="createUser",
     *   @OA\RequestBody(
     *       required=true,
     *       description="Created user object",
     *       @OA\MediaType(
     *           mediaType="multipart/form-data",
     *           @OA\Schema(ref="#/components/schemas/User")
     *       )
     *   ),
     *   @OA\Response(response="default", description="successful operation")
     * )
     */

@OA\Put()

 /**
     * @OA\Put(path="/user/{username}",
     *   tags={"user"},
     *   summary="Updated user",
     *   description="This can only be done by the logged in user.",
     *   operationId="updateUser",
     *   @OA\Parameter(
     *     name="username",
     *     in="path",
     *     description="name that need to be updated",
     *     required=true,
     *     @OA\Schema(
     *         type="string"
     *     )
     *   ),
     *   @OA\Response(response=400, description="Invalid user supplied"),
     *   @OA\Response(response=404, description="User not found"),
     *   @OA\RequestBody(
     *       required=true,
     *       description="Updated user object",
     *       @OA\MediaType(
     *           mediaType="multipart/form-data",
     *           @OA\Schema(ref="#/components/schemas/User")
     *       )
     *   ),
     * )
     */

@OA\Delete()

/**
     * @OA\Delete(path="/user/{username}",
     *   tags={"user"},
     *   summary="Delete user",
     *   description="This can only be done by the logged in user.",
     *   operationId="deleteUser",
     *   @OA\Parameter(
     *     name="username",
     *     in="path",
     *     description="The name that needs to be deleted",
     *     required=true,
     *     @OA\Schema(
     *         type="string"
     *     )
     *   ),
     *   @OA\Response(response=400, description="Invalid username supplied"),
     *   @OA\Response(response=404, description="User not found")
     * )
     */

新增分頁引數

在引數列表中，我們新增兩個名字（name）分別叫做 pageSize 和 pageNumber 的整型（integer）引數，並作簡單描述：

/**
 * @SWG\Get(
 *     path="/persons",
 *     summary="獲取一些人",
 *     description="返回包含所有人的列表。",
 *     @SWG\Parameter(
 *          name="pageSize",
 *          in="query",
 *          description="Number of persons returned",
 *          type="integer"
 *     ),
 *     @SWG\Parameter(
 *          name="pageNumber",
 *          in="query",
 *          description="Page number",
 *          type="integer"
 *     )
 * )
 */

路徑引數（path parameter）

有時候我們想要根據使用者名稱來查詢使用者資訊，這時我們需要增加一個介面操作，比如可以新增一個類似 /persons/{username} 的操作來獲取使用者資訊。注意，{username} 是在請求路徑中的引數。

/**
 * @SWG\Get(
 *     path="/persons/{username}",
 *     summary="獲取一些人",
 *     description="返回包含所有人的列表。",
 *     @SWG\Parameter(
 *          name="username",
 *          in="path",
 *          required=true
 *          description="The person's username",
 *          type="string"
 *     )
 * )
 */

廢棄屬性 deprecated=true

文件生成

php swagge-php/bin/swagger 介面資料夾 -o 生成的目的資料夾

本作品採用《CC 協議》，轉載必須註明作者和本文連結

相關文章