apidoc and swagger are two nice projects which are focusing on documentation of APIs. This project is a middle tier which tries to bring them together in a sense that it uses apidoc to convert inline documentation to json schema and later convert it to swagger json schmea.
When I use the tool to generate swagger docs for a GET method, it creates a definition for the input but doesn't use it. This causes a warning when copying the text into the swagger editor and adds some un-needed cruft to the swagger.json.
For example, here is a sample comment string I'm using.
/**
* @api {get} /store/{storeId}/States/StatesForCountry?countryCode={countryCode}
* @apiName getStatesForCountry
* @apiDescription For a given store and country, returns the list of states/provinces
* @apiGroup Group
*
* @apiParam {String} storeId store id
* @apiParam {String} countryCode country code
*
* @apiSuccess {Array} getStatesForCountryResponse A list of objects containing state information
* @apiSuccess {String} getStatesForCountryResponse.code The 2 letter state code
* @apiSuccess {String} getStatesForCountryResponse.displayName The full display name of the state
*
* @apiError (500) Internal server error
*/
The output swagger has an erroneous getStatesForCountry definition.
Hello,
When I use the tool to generate swagger docs for a
GETmethod, it creates a definition for the input but doesn't use it. This causes a warning when copying the text into the swagger editor and adds some un-needed cruft to the swagger.json.For example, here is a sample comment string I'm using.
The output swagger has an erroneous
getStatesForCountrydefinition.