Ref in @OA\Header

[jwadhams]

It looks like it should be possible, inside a Response, to have a Header that's just a reference to a definition in the Components. Here's an example in the generated yaml: OAI/OpenAPI-Specification#1445 (comment)

I would have expected something like this to work:

 * @OA\Header(
 *     header="X-RateLimit-Remaining",
 *     description="The number of remaining requests in the period",
 *     @OA\Schema( type="integer" )
 * ),
 *
 * @OA\Response(
 *     response="Standard400BadRequestResponse",
 *     description="Bad request, validation error",
 *     @OA\Schema(ref="#/components/schemas/Error"),
 *     @OA\Header(ref="#/components/headers/X-RateLimit-Limit"),
 * ),

but I get the errors Unexpected field "ref" and @OA\Header() is missing key-field: "header"

[bfanger]

Fixed, Thanks for reporting the issue.

Ps:
For now, you still need to specify the header, so inside the @OA\Response you'd write:

 *    @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining")

[jpuck]

@bfanger we're running 3.0.2, which contains the fix in 67f5173 but we still are getting the warning unless specifying the header="X-RateLimit-Remaining" as in your proposed workaround above. thanks!

[bfanger]

@jpuck that is by design, this way you the propertyname in the components.headers object doesn't have to match the propertyname in the response
.headers object.