如何在SwaggerOpenApi中添加JSON请求和响应示例？

如何解决如何在SwaggerOpenApi中添加JSON请求和响应示例？

我在Symfony 4应用程序中有一个API端点，我想使用NelmioApiDocBundle和Swagger进行记录。端点将JSON作为请求数据，并且还返回一些自定义JSON作为响应。如何使用注释将这些示例添加到文档中？我看不到文档页面上的任何示例，仅是描述。

/**
 * @Route("/order/import",methods={"POST"},name="order_import")
 * @OA\RequestBody (
 *     request="order",*     description="Order data in JSON format",*     @OA\Schema(
 *        type="object",*        example={"hello": "world"}
 *     )
 * )
 * @OA\Response(
 *     response=200,*     description="Returns the JSON data after import",*        example={"foo": "bar"}
 *     )
 * )
 * @OA\Tag(name="import")

解决方法

对于NelmioApiDocBundle v4，您可以这样做

use OpenApi\Annotations as OA;

/**
 * @OA\Parameter(
 *     name="body",*     in="path",*     required=true,*     @OA\JsonContent(
 *        type="object",*        @OA\Property(property="property1",type="number"),*        @OA\Property(property="property2",*     ),* )
 *
 * @OA\Response(
 *     response=200,*     description="",*     )
 * )
 */

对于v3

use Swagger\Annotations as SWG;

/**
 * @SWG\Parameter(
 *     name="body",*     in="body",*     @SWG\Schema(
 *         @SWG\Property(property="test1",type="string"),*         @SWG\Property(property="test2",* )
 *
 * @SWG\Response(
 *     description="",*     response=200,* )
 */

但是最好通过@Model注释来实现，如doc中所述，如果您具有DTO或实体。