symfony5之OpenAPI扩展包实现 swagger 文档:
最近需要将之前写的接口出一个文档，准备用一下当前比较流行的swagger，symfony框架下，用这个拓展包:https://github.com/nelmio/NelmioApiDocBundle 就可以了.

基本上composer 安装好以后，配置两个路由: api/doc 和 api/doc.json 就可以了,一个是页面展示小鬼，还有一个是以json文件的形式展示出来

下面是实际使用:
1.post请求注释

/**
 * @OA\Post(
 *     path="/api/post",
 *     summary="Create a new post",
 *     tags={"Posts"},
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(
 *             @OA\Property(property="title", type="string", example="New Post"),
 *             @OA\Property(property="content", type="string", example="This is the content of the post.")
 *         )
 *     ),
 *     @OA\Response(
 *         response="201",
 *         description="Post created successfully",
 *         @OA\JsonContent(
 *             @OA\Property(property="message", type="string", example="Post created successfully.")
 *         )
 *     ),
 *     @OA\Response(
 *         response="400",
 *         description="Bad request",
 *         @OA\JsonContent(
 *             @OA\Property(property="message", type="string", example="Invalid input data.")
 *         )
 *     )
 * )
 */
  
在这个示例中，我们使用 @OA\Post 注释来定义一个 POST 请求。path 参数指定了 API 的路径，summary 提供了关于此操作的简要描述，tags 列出了相关的标签。@OA\RequestBody 用于定义请求体，这里我们使用 @OA\JsonContent 来指定请求体的 JSON 格式。@OA\Response 用于定义操作的响应，包括成功和错误情况。

2.post参数为枚举类型

/**
 * @OA\Post(
 *     path="/api/create_order",
 *     summary="Create a new order",
 *     tags={"Orders"},
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(
 *             @OA\Property(property="product", type="string", enum={"product1", "product2", "product3"}),
 *             @OA\Property(property="quantity", type="integer", example=10)
 *         )
 *     ),
 *     @OA\Response(
 *         response="201",
 *         description="Order created successfully",
 *         @OA\JsonContent(
 *             @OA\Property(property="message", type="string", example="Order created successfully.")
 *         )
 *     ),
 *     @OA\Response(
 *         response="400",
 *         description="Bad request",
 *         @OA\JsonContent(
 *             @OA\Property(property="message", type="string", example="Invalid input data.")
 *         )
 *     )
 * )
 */
  
在上面的示例中，@OA\Schema 注释用于定义一个枚举类型的对象。在 @OA\Property 注释中，使用 enum 参数来指定允许的枚举值列表。这里我们定义了一个名为 "product" 的字段，其类型为字符串，且仅允许取值为 "product1"、"product2" 和 "product3" 中的一个。

3.post返回值包含对象

/**
 * @OA\Post(
 *     summary="Create a new post",
 *     tags={"Posts"},
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(
 *             @OA\Property(property="title", type="string"),
 *             @OA\Property(property="content", type="string")
 *         )
 *     ),
 *     @OA\Response(
 *         response="201",
 *         description="Post created successfully",
 *         @OA\JsonContent(
 *             @OA\Property(property="message", type="string", example="Post created successfully."),
 *             @OA\Property(property="post_data", type="object",
 *                 @OA\Property(property="id", type="integer", example=123),
 *                 @OA\Property(property="title", type="string"),
 *                 @OA\Property(property="content", type="string")
 *             )
 *         )
 *     ),
 *     @OA\Response(
 *         response="400",
 *         description="Bad request",
 *         @OA\JsonContent(
 *             @OA\Property(property="message", type="string", example="Invalid input data.")
 *         )
 *     )
 * )
 */
  
在这个示例中，@OA\Response 注解用于描述响应。在 @OA\JsonContent 注解中，我们使用 @OA\Property 来定义响应的属性。其中，post_data 是一个对象属性，我们在它的内部使用另一个 @OA\Property 注解来定义该对象的属性，如 id、title 和 content。

4.普通GET请求

/**
 * @OA\Get(
 *     path="/api/resource",
 *     summary="Get a list of resources",
 *     tags={"Resource"},
 *     @OA\Response(
 *         response=200,
 *         description="Successful response",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(ref="#/components/schemas/Resource")
 *         )
 *     )
 * )
 */
  
在上面的示例中，@OA\Get 注释表示这是一个 GET 请求的配置。您需要指定请求的路径、概要、标签和响应。响应部分使用 @OA\Response 注释来定义成功响应的状态码和数据结构。

5.带一个id路由参数的GET请求

/**
 * @OA\Get(
 *     path="/api/resource/{id}",
 *     summary="Get a resource by ID",
 *     tags={"Resource"},
 *     @OA\Parameter(
 *         name="id",
 *         in="path",
 *         required=true,
 *         description="ID of the resource",
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="Successful response",
 *         @OA\JsonContent(ref="#/components/schemas/Resource")
 *     )
 * )
 */
  
在上面的示例中，我们在路径中使用 {id} 来表示路由参数，然后使用 @OA\Parameter 注释来定义这个参数。注释中的属性说明如下：

name: 参数的名称，这里是 "id"。
in: 参数的位置，这里是 "path"，表示在 URL 路径中。
required: 参数是否为必需的，这里设置为 true。
description: 参数的描述，解释了该参数的用途。
@OA\Schema(type="integer"): 参数的数据类型，这里设置为整数类型。

6.@OA\Property 和 @OA\Parameter 的区别

@OA\Property 和 @OA\Parameter 都是 Swagger-PHP 中用于描述 API 文档的注解，但它们在使用场景和含义上有一些区别。
  
@OA\Property:
用于描述请求体或响应体中的属性。通常用于描述 POST、PUT 等请求方法中的请求体的属性，或者响应中的属性。
适用于描述实体对象的属性，例如请求体中的字段、响应中的字段、嵌套对象等。
可以设置类型、示例值、描述等属性。
用于展示请求体和响应体中的属性。
  
@OA\Parameter:
用于描述 URL 路径参数、查询参数、标头参数等。
适用于描述作为请求参数的属性，例如 GET 请求中的查询参数，或者 URL 中的路径参数。
可以设置类型、示例值、描述等属性。
用于展示接口的输入参数。

7.总结
其实这个swagger-php 的使用，主要就是属性的嵌套，习惯就好，唯一不好的就是，整个php代码会显得十分臃肿，主要还是注释部分