查询参数的 Swagger 注释

Posted 2023-02-16

【中文标题】查询参数的 Swagger 注释

【英文标题】：Swagger annotation for query parameters

【发布时间】：2020-03-03 04:28:05

【问题描述】：

我正在将 POST 请求转换为 GET 请求。我正在使用 NelmioApiDocBundle 来记录我的 API 端点。我目前有以下（旧）注释：

/**
 * @SWG\Response(
 *     response=200,
 *     description="Success - return JSON",
 * )
 * @SWG\Tag(name="Open Vacancies")
 *
 * @SWG\Parameter(
 *     name="Message body",
 *     in="body",
 *     type="string",
 *     description="JSON string specifying a page number and page size",
 *     required=true,
 *     @SWG\Schema(
 *         type="object",
 *         @SWG\Property(property="page", type="integer"),
 *         @SWG\Property(property="pageSize", type="integer")
 *     )
 * )
 *
 * @Route("/open-vacancies", methods="POST", defaults="_format": "json", name="api.open_vacancies")
 */

现在我希望开发人员能够使用像 https://myapi.myapp.com/open-vacancies?page=1&pageSize=10 这样的 URL 来调用我的端点。但我不知道如何以注释形式定义文档。谷歌对我帮助不大。有人可以向我指出相关文档（或者，如果失败，请输入我可以使用的注释示例）？

【问题讨论】：

prnt.sc/ptbroysymfony.com/doc/current/bundles/NelmioApiDocBundle/index.html

【参考方案1】：

要记录查询参数，您也可以使用@SWG\Parameter 注释，但您将in 的值设置为query 而不是body

例子：

/**
 * @SWG\Parameter(
 *     name="pageSize",
 *     in="query",
 *     type="string",
 *     description="Description goes here"
 * )
 */