需在Swagger/OpenAPI文档中清晰标注Laravel接口限流策略：PHP注解用x-rate-limit扩展字段定义limit/period/key，支持多级限流嵌套；YAML中统一在components定义响应头与错误模型，并在paths中引用预设模板；429响应须显式声明并提供Retry-After头及reset_time示例。
为Laravel项目中使用Swagger/OpenAPI文档清晰标注接口限流策略，需在注解或YAML定义中准确体现速率限制规则、触发条件与响应行为，避免开发者误判接口可用性。
在PHP注解中声明限流配置
使用@OA\Get等操作注解时，在extensions字段内嵌入自定义限流描述。
第一步：在控制器方法上方的OpenAPI注解块中，添加"x-rate-limit"扩展字段。
第二步：为该字段赋值为关联数组，包含limit（单位时间最大请求数）、period（时间窗口秒数）、key（限流维度标识符，如"ip"或"user_id"）三项必填键。
第三步：若接口存在多级限流（如基础IP限流+登录用户增强限流），需用数组嵌套方式表达，外层为默认策略，内层通过conditions指定适用场景，例如"auth:api"中间件生效时启用更高阈值。
注意：Laravel Swagger UI默认不渲染x-开头的扩展字段，必须配合定制化的UI插件或后端文档中间件才能可视化展示，否则仅作为元数据存在。
在openapi.yaml中统一定义限流信息
适用于团队共用规范文档、需脱离代码生成独立维护的场景。
在components/headers下新增X-RateLimit-Limit与X-RateLimit-Remaining标准响应头定义；在components/schemas中补充RateLimitError错误模型。
为每个需要限流的path操作节点添加x-rate-limit对象，结构同PHP注解方式，但支持引用components/x-rate-limit-presets中的预设模板，例如{"$ref": "#/components/x-rate-limit-presets/burst"}。
【presets必须预先在文档根级components下声明，否则引用失效】
标注限流触发后的HTTP响应
方法一：在对应接口的responses中显式添加429状态码分支。
填写description为“请求过于频繁，请稍后再试”，并在content中定义返回体格式，推荐复用application/json下的ErrorResponse schema。
方法二：使用examples字段提供典型限流响应示例，包含Retry-After响应头值（单位秒）与JSON body中的message和reset_time时间戳字段。
这一步操作起来很简单，直接把示例粘贴进examples区块即可，但务必确保reset_time格式与后端实际输出一致（UTC ISO8601或Unix timestamp）。
