如何在 Swagger (OpenApi) 中添加 JSON 请求和响应示例？

Question

我的 Symfony 4 应用程序中有一个 API 端点，我想用 NelmioApiDocBundle 和 Swagger 记录它。端点将 JSON 作为请求数据，并将 returns 一些自定义 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",
 *     @OA\Schema(
 *        type="object",
 *        example={"foo": "bar"}
 *     )
 * )
 * @OA\Tag(name="import")

Answer 1

对于 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", type="number"),
 *     ),
 * )
 *
 * @OA\Response(
 *     response=200,
 *     description="",
 *     @OA\JsonContent(
 *        type="object",
 *        @OA\Property(property="property1", type="number"),
 *        @OA\Property(property="property2", type="number"),
 *     )
 * )
 */

对于 v3

use Swagger\Annotations as SWG;

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

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

如何在 Swagger (OpenApi) 中添加 JSON 请求和响应示例？

How to add JSON request and response examples in Swagger (OpenApi)?

symfony

swagger

swagger-ui

openapi

nelmioapidocbundle