I'm using the Restler framework to write my API, and it uses swagger to document things. When I define my method I'm having two issues with the resulting documentation. One is that the description of the parameters is not being displayed in swagger, and the other is that it is saying they are all required. How do I flag them as being optional in the documentation? I'm doing something like the below, where categories and picture are optional parameters.
/**
* 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 = '') {
Update: If you are using Explorer class in RC6 and optional parameters are still showing up as required, download the latest update. We just released a fix for this!
Your example is right, we mark the optional parameters by specifying default value in PHP. Thats enough to document them as optional. If you want more clarity you may add (optional) in the description of those parameters as well