OpenAPI文档不会自动识别PHP分页逻辑，必须手动用@OA\Parameter声明page和page_size等查询参数，并在@OA\Response中显式定义meta分页字段，否则Swagger UI不显示输入框且响应结构缺失分页信息。
PHP翻页逻辑本身不生成OpenAPI文档
OpenAPI文档不会因为你写了$page和$page_size参数就自动识别为分页接口。它只认显式声明的元数据——比如@OA\Get里是否定义了@OA\Parameter，以及这些参数是否被标记为分页语义（如name="page"、in="query"、schema={"type":"integer"}）。纯业务代码里的变量名、计算逻辑、SQL偏移量，对swagger-php完全不可见。
必须手动在OpenAPI注解中声明分页参数
即使你的控制器方法内部用$_GET['page']或Request $request取值，也要在@OA\Get或@OA\Post注释块里逐个写出@OA\Parameter，否则生成的openapi.json里不会有这些字段，Swagger UI也就不会显示输入框。
@OA\Parameter(name="page", in="query", description="页码，从1开始", required=false, schema={"type":"integer","default":1,"minimum":1})@OA\Parameter(name="page_size", in="query", description="每页数量，最大50", required=false, schema={"type":"integer","default":10,"minimum":1,"maximum":50})- 如果用了
Pageable这类封装对象（如Laravel的LengthAwarePaginator），仍需拆解为独立参数——OpenAPI不理解框架内部对象，只认扁平化的HTTP参数结构
避免把分页参数写成请求体或路径参数
分页参数几乎总是查询参数（in="query"），写成in="path"会导致URL变成/api/users/{page}，这不符合REST惯例；写成in="body"则违背GET请求不能带body的HTTP规范，且swagger-php对GET的@OA\RequestBody支持有限，容易被忽略。
- 错误示例：
@OA\Parameter(name="page", in="path", ...)→ 生成的路径会强制要求URL含/1，丧失可选性 - 错误示例：
@OA\RequestBody(@OA\JsonContent(...))用于GET → 大部分客户端不发送body，Swagger UI也不渲染输入框 - 正确位置：所有分页参数都放在
@OA\Get的parameters={...}数组内，in="query"
响应体里要体现分页元信息才完整
仅声明请求参数不够。前端需要知道“当前第几页”“总共有多少页”“是否还有下一页”，这些得靠响应结构返回。OpenAPI文档必须同步描述响应里的meta或pagination字段，否则生成的SDK或Mock服务无法处理分页上下文。
立即学习“PHP免费学习笔记（深入）”；
- 在
@OA\Response的@OA\JsonContent中嵌套分页字段，例如：@OA\Property(property="meta", type="object", @OA\Property(property="current_page", type="integer"), @OA\Property(property="last_page", type="integer")) - 不要只写
@OA\JsonContent(type="array", @OA\Items(...))——那只是数据列表，没包含分页控制信息 - 如果用
LengthAwarePaginator返回JSON，Laravel默认已含current_page、last_page等字段，但OpenAPI注解仍需显式描述，否则文档和实际响应脱节
openapi.json里的responses["200"]["content"]["application/json"]["schema"]仍然只描述一个纯数组，导致前端开发者以为接口没返回分页信息，只能自己猜或查源码。 
