在 swagger 文档中将 restler 方法参数标记为可选
Mark restler method param as optional in swagger documentation
我正在使用 Restler 框架编写我的 API,它使用 swagger 来记录内容。当我定义我的方法时,生成的文档有两个问题。一个是参数的描述没有大摇大摆地显示,另一个是它说它们都是必需的。如何在文档中将它们标记为可选?我正在做类似下面的事情,其中类别和图片是可选参数。
/**
* Create a new News post
*
* Creates a new News post
*
* @param string $title The title of the task.
* @param string $url The URL of the webpage to display.
* @param string $body The text of the news article.
* @param int $team_id The sql_ident of the Team this news article relates to.
* @param string $categories The comma separated list of categories.
* @param string $picture The URL to the picture to display.
*
* @status 201
*
* @return array The sql_ident of the new article
*/
function post($title, $url, $body, $team_id, $categories = '', $picture = '') {
更新: 如果您在 RC6 中使用资源管理器 class,并且可选参数仍按要求显示,请下载最新更新。我们刚刚发布了一个修复程序!
你的例子是正确的,我们通过在PHP中指定默认值来标记可选参数。这足以将它们记录为可选的。如果你想要更清楚,你也可以在这些参数的描述中添加 (optional)
我正在使用 Restler 框架编写我的 API,它使用 swagger 来记录内容。当我定义我的方法时,生成的文档有两个问题。一个是参数的描述没有大摇大摆地显示,另一个是它说它们都是必需的。如何在文档中将它们标记为可选?我正在做类似下面的事情,其中类别和图片是可选参数。
/**
* Create a new News post
*
* Creates a new News post
*
* @param string $title The title of the task.
* @param string $url The URL of the webpage to display.
* @param string $body The text of the news article.
* @param int $team_id The sql_ident of the Team this news article relates to.
* @param string $categories The comma separated list of categories.
* @param string $picture The URL to the picture to display.
*
* @status 201
*
* @return array The sql_ident of the new article
*/
function post($title, $url, $body, $team_id, $categories = '', $picture = '') {
更新: 如果您在 RC6 中使用资源管理器 class,并且可选参数仍按要求显示,请下载最新更新。我们刚刚发布了一个修复程序!
你的例子是正确的,我们通过在PHP中指定默认值来标记可选参数。这足以将它们记录为可选的。如果你想要更清楚,你也可以在这些参数的描述中添加 (optional)