php-swagger 3.0版本
Swagger注解编写
请求方式
@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 协议》,转载必须注明作者和本文链接
推荐文章: