Swagger-php: Examples in Response to show response samples

[ekumahost]

This code works in my previous project but is throwing error in my today project why.

Notice: Unexpected field "examples" for @OA\Response(), expecting "ref",...
```
@OA\Response(
response=200,
description="successful operation",
examples={
"application/json": {
"name"="Puma",
"type"="Dog",
"color"="Black",
"gender"="Female",
"breed"="Mixed"
}
}
),

```
Am confused, do we have a new version, I think my old and new project is version 3 too.
Who actually have a perfect documentation link with the items listed well.

[ekumahost]

I also saw this warning:

NOTICE: Unexpected field \"consumes\" for @OA\\Post(), expecting \"method\", \"path\", \"tags\", \"summary\", \"description\",

these things are no longer funny, "consumes" is used in OA\Post options, how did it get deprecated I just don't understand, there is just no standard documentation..

[mtyeh411]

i'm new to using swagger-php, but how Examples is being handled does not seem to adhere to OAS 3.0

i suspect that this is an incomplete list of allowable parents (with missing correlating pointers from the parents):
https://github.com/zircote/swagger-php/blob/ff3969977b/src/Annotations/Examples.php#L60-L64

also according the example in the specs, Examples should be able to be referenced

OAS specs:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#example-object-example

[xingtianyoulong]

@ekumahost, I try so hard by myself, so I find the answer now:

     *     @OA\Response(
     *         response="200",
     *         description="ok",
     *         content={
     *             @OA\MediaType(
     *                 mediaType="application/json",
     *                 @OA\Schema(
     *                     @OA\Property(
     *                         property="errcode",
     *                         type="integer",
     *                         description="The response code"
     *                     ),
     *                     @OA\Property(
     *                         property="errmsg",
     *                         type="string",
     *                         description="The response message"
     *                     ),
     *                     @OA\Property(
     *                         property="data",
     *                         type="array",
     *                         description="The response data",
     *                         @OA\Items
     *                     ),
     *                     example={
     *                         "errcode": 1,
     *                         "errmsg": "ok",
     *                         "data": {}
     *                     }
     *                 )
     *             )
     *         }
     *     )

[ihamzehald]

I am adding a sample of full custom post request the response structure from @xingtianyoulong comment and it is working as expected:

/**
 * @OA\Post(
 *   path="/auth/jwt/login",
 *   tags={"Auth"},
 *   summary="JWT login",
 *   description="Login a user and generate JWT token",
 *   operationId="jwtLogin",
 *   @OA\RequestBody(
 *       required=true,
 *       @OA\MediaType(
 *           mediaType="application/json",
 *           @OA\Schema(
 *               type="object",
 *               @OA\Property(
 *                   property="email",
 *                   description="User email",
 *                   type="string",
 *                   example="[email protected]"
 *               ),
 *               @OA\Property(
 *                   property="password",
 *                   description="User password",
 *                   type="string",
 *                   example="larapoints123"
 *               ),
 *           )
 *       )
 *   ),
 *  @OA\Response(
 *         response="200",
 *         description="ok",
 *         content={
 *             @OA\MediaType(
 *                 mediaType="application/json",
 *                 @OA\Schema(
 *                     @OA\Property(
 *                         property="access_token",
 *                         type="string",
 *                         description="JWT access token"
 *                     ),
 *                     @OA\Property(
 *                         property="token_type",
 *                         type="string",
 *                         description="Token type"
 *                     ),
 *                     @OA\Property(
 *                         property="expires_in",
 *                         type="integer",
 *                         description="Token expiration in miliseconds",
 *                         @OA\Items
 *                     ),
 *                     example={
 *                         "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
 *                         "token_type": "bearer",
 *                         "expires_in": 3600
 *                     }
 *                 )
 *             )
 *         }
 *     ),
 *   @OA\Response(response="401",description="Unauthorized"),
 * )
 */

[jeff-browne]

I am adding a sample of full custom post request the response structure from @xingtianyoulong comment and it is working as expected:

/**
 * @OA\Post(
 *   path="/auth/jwt/login",
 *   tags={"Auth"},
 *   summary="JWT login",
 *   description="Login a user and generate JWT token",
 *   operationId="jwtLogin",
 *   @OA\RequestBody(
 *       required=true,
 *       @OA\MediaType(
 *           mediaType="application/json",
 *           @OA\Schema(
 *               type="object",
 *               @OA\Property(
 *                   property="email",
 *                   description="User email",
 *                   type="string",
 *                   example="[email protected]"
 *               ),
 *               @OA\Property(
 *                   property="password",
 *                   description="User password",
 *                   type="string",
 *                   example="larapoints123"
 *               ),
 *           )
 *       )
 *   ),
 *  @OA\Response(
 *         response="200",
 *         description="ok",
 *         content={
 *             @OA\MediaType(
 *                 mediaType="application/json",
 *                 @OA\Schema(
 *                     @OA\Property(
 *                         property="access_token",
 *                         type="string",
 *                         description="JWT access token"
 *                     ),
 *                     @OA\Property(
 *                         property="token_type",
 *                         type="string",
 *                         description="Token type"
 *                     ),
 *                     @OA\Property(
 *                         property="expires_in",
 *                         type="integer",
 *                         description="Token expiration in miliseconds",
 *                         @OA\Items
 *                     ),
 *                     example={
 *                         "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
 *                         "token_type": "bearer",
 *                         "expires_in": 3600
 *                     }
 *                 )
 *             )
 *         }
 *     ),
 *   @OA\Response(response="401",description="Unauthorized"),
 * )
 */

https://github.com/zircote/swagger-php/issues/820#issue-665109198