How to use Swagger/OpenAPI annotations in PHP to describe a Cookie?

Question

When using the block below to generate swagger documentation:

/**
 * @OA\Get(
 *     path="/api/users",
 *     summary="...",
 *     @OA\Response(
 *         response="200",
 *         description="...",
 *         @OA\Cookie(
 *             name="my_cookie",
 *             description="...",
 *             @OA\Schema(
 *                 type="string"
 *             )
 *         )
 *     )
 * )
 */

I get an error message similar to:

[Syntax Error] Expected Doctrine\Common\Annotations\DocLexer::T_CLOSE_PARENTHESIS, got '@' in...

What could be wrong?

Answer 1

According to the OpenAPI documentation, when you want to describe the cookie sent with the response, you should describe it through the Set-Cookie header.

You could then implement it like this with OA Annotations :

    /**
     * @OA\Get(
     *     path="/api/users",
     *     summary="...",
     *     @OA\Response(
     *        response="200",
     *        description="...",
     *        @OA\Header(
     *            header="Set-Cookie",
     *            @OA\Schema(
     *                  type="string",
     *                  example="Some value"
     *            )
     *        )
     *    )
     * )
     */

Answer 2

You should move the @OA\Cookie annotation to the top level of your documentation block.

/**
 * @OA\Get(
 *     path="/api/users",
 *     summary="...",
 * )
 *
 * @OA\Cookie(
 *     name="my_cookie",
 *     description="...",
 *     @OA\Schema(
 *         type="string"
 *     )
 * )
 */