Visual Studio Code API Doc snipppets.

javascript.json

/** 
 * For more info on how to create snippets in VS Code, 
 * visit https://code.visualstudio.com/Docs/customization/userdefinedsnippets
 */
{
	"API Documentation": {
		"prefix": "apidocs",
		"body": [
			"/**",
			"* @api {${1:http-method}} ${2:url} ${3:description}",
			"* @apiVersion ${4:version}",
			"* @apiName ${5:serviceName}",
			"* @apiGroup ${6:groupName}",
			"*",
			"* @apiParam {${7:type}} ${8:paramName} ${9:description}",
			"*",
			"* @apiSuccess {Array} links Available hypermedia links for a specific resource.",
			"* @apiSuccess {${10:type}} ${11:fieldName} ${12:description}",
			"*",
			"* @apiSuccessExample Success-Response:",
			"*     HTTP/1.1 200 OK",
			"*     {",
			"*       \"links\": [",
			"*         {",
			"*           \"method\": \"GET\",",
			"*           \"rel\": \"self\",",
			"*           \"href\": \"http://localhost:8080/${2:url}/\"",
			"*         }",
			"*       ],",
			"*       \"field\": \"value\"",
			"*     }",
			"*",
			"* @apiError ${13:errorName} ${14:description}",
			"* @apiErrorExample ${13:errorName}:",
			"*     HTTP/1.1 ${15:errorCode} Internal Server Error",
			"*     {",
			"*       \"message\": \"${16:error description.}\",",
			"*       \"error\": {",
			"*         \"status\": ${15:errorCode}",
			"*       }",
			"*     }",
			"**/"
		],
		"description": "API annotations to use with services that return a single resource."
	},
	"Auth API Documentation": {
		"prefix": "apidocs_auth",
		"body": [
			"/**",
			"* @api {${1:http-method}} ${2:url} ${3:description}",
			"* @apiVersion ${4:version}",
			"* @apiName ${5:serviceName}",
			"* @apiGroup ${6:groupName}",
			"*",
			"* @apiParam {${7:type}} ${8:paramName} ${9:description}",
			"*",
			"* @apiSuccess {Array} links Available hypermedia links for a specific resource.",
			"* @apiSuccess {${10:type}} ${11:fieldName} ${12:description}",
			"*",
			"* @apiSuccessExample Success-Response:",
			"*     HTTP/1.1 200 OK",
			"*     {",
			"*       \"links\": [",
			"*         {",
			"*           \"method\": \"GET\",",
			"*           \"rel\": \"self\",",
			"*           \"href\": \"http://localhost:8080/${2:url}/\"",
			"*         }",
			"*       ],",
			"*       \"field\": \"value\"",
			"*     }",
			"*",
			"* @apiError UNAUTHORIZED_TOKEN Unauthorized request (not authenticated or invalid token provided).",
			"* @apiErrorExample UNAUTHORIZED_TOKEN:",
			"*     HTTP/1.1 401 Unauthorized",
			"*     {",
			"*       \"message\": \"Unauthorized\",",
			"*       \"error\": {",
			"*         \"status\": 401",
			"*       }",
			"*     }",
			"*",
			"* @apiError UNAUTHORIZED_ROLE User doesn't have the required role(s).",
			"* @apiErrorExample UNAUTHORIZED_ROLE:",
			"*     HTTP/1.1 401 Unauthorized",
			"*     {",
			"*       \"message\": \"Your user does not have the required role(s) to execute this action.\",",
			"*       \"error\": {",
			"*         \"status\": 401",
			"*       }",
			"*     }",
			"*",
			"* @apiError ${13:errorName} ${14:description}",
			"* @apiErrorExample ${13:errorName}:",
			"*     HTTP/1.1 ${15:errorCode} Internal Server Error",
			"*     {",
			"*       \"message\": \"${16:error description.}\",",
			"*       \"error\": {",
			"*         \"status\": ${15:errorCode}",
			"*       }",
			"*     }",
			"**/"
		],
		"description": "API annotations to use with services that return a single resource. Authentication responses included."
	},
	"API Documentation (collection)": {
		"prefix": "apidocs_col",
		"body": [
			"/**",
			"* @api {${1:http-method}} ${2:url} ${3:description}",
			"* @apiVersion ${4:version}",
			"* @apiName ${5:serviceName}",
			"* @apiGroup ${6:groupName}",
			"*",
			"* @apiParam {Number} page Optional page number. Default value: 0",
			"* @apiParam {Number} pageSize Optional page size. Default value: 10",
			"*",
			"* @apiSuccess {Number} totalPages Total amount of pages.",
			"* @apiSuccess {Number} totalCount  Total amount of records.",
			"* @apiSuccess {Link} prevPage Link to navigate to collection's previous page.",
			"* @apiSuccess {Link} nextPage Link to navigate to collection's next page.",
			"* @apiSuccess {Array} data Array of resource objects with hypermedia links.",
			"* @apiSuccess {Array} links Available hypermedia links for a specific resource.",
			"*",
			"* @apiSuccessExample Success-Response:",
			"*     HTTP/1.1 200 OK",
			"*     {",
			"*       \"totalPages\": 2,",
			"*       \"totalCount\": 20,",
			"*       \"data\": [",
			"*         {",
			"*          \"links\": [",
			"*             {",
			"*               \"method\": \"GET\",",
			"*               \"rel\": \"self\",",
			"*               \"href\": \"http://localhost:8080/${2:url}/\"",
			"*             }",
			"*           ],",
			"*           \"field\": \"value\",",
			"*         },",
			"*         ...",
			"*       ],",
			"*       \"prevPage\": null,",
			"*       \"nextPage\": \"http://localhost:8080/${2:url}?page=2\"",
			"*     }",
			"*",
			"* @apiError INVALID_PAGE_NUMBER Invalid page number provided.",
			"* @apiErrorExample INVALID_PAGE_NUMBER:",
			"*     HTTP/1.1 500 Internal Server Error",
			"*     {",
			"*       \"message\": \"You must provide a page number.\",",
			"*       \"error\": {",
			"*         \"status\": 500",
			"*       }",
			"*     }",
			"*",
			"* @apiError INVALID_PAGE_SIZE Invalid page size provided.",
			"* @apiErrorExample INVALID_PAGE_SIZE:",
			"*     HTTP/1.1 500 Internal Server Error",
			"*     {",
			"*       \"message\": \"Page size must be a number.\",",
			"*       \"error\": {",
			"*         \"status\": 500",
			"*       }",
			"*     }",
			"*",
			"* @apiError ${7:errorName} ${8:description}",
			"* @apiErrorExample ${7:errorName}:",
			"*     HTTP/1.1 ${9:errorCode} Internal Server Error",
			"*     {",
			"*       \"message\": \"${10:error description.}\",",
			"*       \"error\": {",
			"*         \"status\": ${9:errorCode}",
			"*       }",
			"*     }",
			"**/"
		],
		"description": "API annotations to use with services that return a collection of resources."
	},
	"Auth API Documentation (collection)": {
		"prefix": "apidocs_col_auth",
		"body": [
			"/**",
			"* @api {${1:http-method}} ${2:url} ${3:description}",
			"* @apiVersion ${4:version}",
			"* @apiName ${5:serviceName}",
			"* @apiGroup ${6:groupName}",
			"*",
			"* @apiParam {Number} page Optional page number. Default value: 0",
			"* @apiParam {Number} pageSize Optional page size. Default value: 10",
			"*",
			"* @apiSuccess {Number} totalPages Total amount of pages.",
			"* @apiSuccess {Number} totalCount  Total amount of records.",
			"* @apiSuccess {Link} prevPage Link to navigate to collection's previous page.",
			"* @apiSuccess {Link} nextPage Link to navigate to collection's next page.",
			"* @apiSuccess {Array} data Array of resource objects with hypermedia links.",
			"* @apiSuccess {Array} links Available hypermedia links for a specific resource.",
			"*",
			"* @apiSuccessExample Success-Response:",
			"*     HTTP/1.1 200 OK",
			"*     {",
			"*       \"totalPages\": 2,",
			"*       \"totalCount\": 20,",
			"*       \"data\": [",
			"*         {",
			"*          \"links\": [",
			"*             {",
			"*               \"method\": \"GET\",",
			"*               \"rel\": \"self\",",
			"*               \"href\": \"http://localhost:8080/${2:url}/\"",
			"*             }",
			"*           ],",
			"*           \"field\": \"value\",",
			"*         },",
			"*         ...",
			"*       ],",
			"*       \"prevPage\": null,",
			"*       \"nextPage\": \"http://localhost:8080/${2:url}?page=2\"",
			"*     }",
			"*",
			"* @apiError UNAUTHORIZED_TOKEN Unauthorized request (not authenticated or invalid token provided).",
			"* @apiErrorExample UNAUTHORIZED_TOKEN:",
			"*     HTTP/1.1 401 Unauthorized",
			"*     {",
			"*       \"message\": \"Unauthorized\",",
			"*       \"error\": {",
			"*         \"status\": 401",
			"*       }",
			"*     }",
			"*",
			"* @apiError UNAUTHORIZED_ROLE User doesn't have the required role(s).",
			"* @apiErrorExample UNAUTHORIZED_ROLE:",
			"*     HTTP/1.1 401 Unauthorized",
			"*     {",
			"*       \"message\": \"Your user does not have the required role(s) to execute this action.\",",
			"*       \"error\": {",
			"*         \"status\": 401",
			"*       }",
			"*     }",
			"*",
			"* @apiError INVALID_PAGE_NUMBER Invalid page number provided.",
			"* @apiErrorExample INVALID_PAGE_NUMBER:",
			"*     HTTP/1.1 500 Internal Server Error",
			"*     {",
			"*       \"message\": \"You must provide a page number.\",",
			"*       \"error\": {",
			"*         \"status\": 500",
			"*       }",
			"*     }",
			"*",
			"* @apiError INVALID_PAGE_SIZE Invalid page size provided.",
			"* @apiErrorExample INVALID_PAGE_SIZE:",
			"*     HTTP/1.1 500 Internal Server Error",
			"*     {",
			"*       \"message\": \"Page size must be a number.\",",
			"*       \"error\": {",
			"*         \"status\": 500",
			"*       }",
			"*     }",
			"*",
			"* @apiError ${7:errorName} ${8:description}",
			"* @apiErrorExample ${7:errorName}:",
			"*     HTTP/1.1 ${9:errorCode} Internal Server Error",
			"*     {",
			"*       \"message\": \"${10:error description.}\",",
			"*       \"error\": {",
			"*         \"status\": ${9:errorCode}",
			"*       }",
			"*     }",
			"**/"
		],
		"description": "API annotations to use with services that return a collection of resources. Authentication responses included."
	},
	"API Parameter Field":{
		"prefix": "api_param",
		"body":[
			"* @apiParam {${1:type}} ${2:fieldName} ${3:description}"
		],
		"description": "API parameter field configuration."
	},
	"API Success Response Field": {
		"prefix": "api_success",
		"body": [
			"* @apiSuccess {${1:type}} ${2:fieldName} ${3:description}"
		],
		"description": "API respose field configuration."
	},
	"API Error Response Field": {
		"prefix": "api_error",
		"body": [
			"* @apiError ${1:errorName} ${2:description}",
			"* @apiErrorExample ${1:errorName}:",
			"*     HTTP/1.1 ${3:errorCode} ${4:error description}",
			"*     {",
			"*       \"message\": \"${4:error description}\",",
			"*       \"error\": {",
			"*         \"status\": ${3:errorCode}",
			"*       }",
			"*     }"
		],
		"description": "API error response configuration."
	}
}

@kevinpr_007