我正在编写OpenAPI规范并尝试从请求路由/路径的注释中自动生成可能的查询参数(使用swagger-php)。我知道我可以为每个路由键入所有可能的参数选项,但我真的需要能够使用注释自动生成类的属性中的可能参数,就像我可以为请求体做的那样。 (我们将拥有大量的类/路径并保持最新状态,除非它们像请求体/ JsonContent一样生成,否则它们很可能不会发生。这一般是swagger-php甚至是OpenAPI吗?
我得到了这个与put和请求体一起工作,但是如何为仍然使用类的属性的get请求执行此操作?
我可以为请求正文执行此操作:
/**
* @return Response
*
* * @OA\Put(
* path="/persons",
* tags={"Person"},
* @OA\RequestBody(
* request="person",
* required=false,
* description="Optional Request Parameters for Querying",
* @OA\JsonContent(ref="#/components/schemas/Person")
* ),
* @OA\Response(
* response="200",
* description="Returns matching Person Object",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Person")
* )
* )
* )
*/
写出30多个类的每个参数将无法维护:
/** @OA\Get(
* path="/events",
* tags={"Events"},
* @OA\Parameter(
* name="eventID",
* in="query",
* required=false,
* description="The event ID specific to this event",
* @OA\Schema(
* type="string"
* ),
* ),
*
* ....etc
Swagger-PHP需要注释来记录查询参数。您可以通过添加可以使用@OA\Parameter
引用的顶级$ref="#/components/parameters/PARAM_NAME"
注释来减少代码重复,如here和here所示。
/**
* @OA\Parameter(
* parameter="eventID_in_query",
* name="eventID",
* description="The event ID specific to this event",
* @OA\Schema(
* type="string"
* ),
* in="query",
* required=false
* )
*/
...
/** @OA\Get(
* path="/events",
* tags={"Events"},
* @OA\Parameter(ref="#/components/parameters/eventID_in_query"),