Я написал RESTful API с Slim Framework. Для документации я хочу пользователя APIDoc.
Я установил apidoc через npm (не работал без sudo)
$ sudo npm install apidoc -g
Я вставил этот пример аннотации в один файл проекта (users.router.php)
/**
* @ApiDescription(section="User", description="Get information about user")
* @ApiMethod(type="get")
* @ApiRoute(name="/user/get/{id}")
* @ApiParams(name="id", type="integer", nullable=false, description="User id")
* @ApiParams(name="data", type="object", sample="{'user_id':'int','user_name':'string','profile':{'email':'string','age':'integer'}}")
* @ApiReturnHeaders(sample="HTTP 200 OK")
* @ApiReturn(type="object", sample="{
* 'transaction_id':'int',
* 'transaction_status':'string'
* }")
*/
Я также добавил файл apidoc.json. Затем я пытаюсь сгенерировать документ по телефону
$ apidoc -i App/Routers/ -o public/doc/
При попытке создать документ появляется несколько ошибок:
apidoc: parser plugin "apimethod" not found.
apidoc: parser plugin "apiroute" not found.
apidoc: parser plugin "apiparams" not found.
apidoc: parser plugin "apiparams" not found.
apidoc: parser plugin "apireturnheaders" not found.
apidoc: parser plugin "apireturn" not found.
Это полный вывод:
apidoc: load parser: api, ./parsers/api.js
apidoc: load parser: apidefineerrorstructure, ./parsers/api_define_error_structure.js
apidoc: load parser: apidefineheaderstructure, ./parsers/api_define_header_structure.js
apidoc: load parser: apidefinepermission, ./parsers/api_define_permission.js
apidoc: load parser: apidefinestructure, ./parsers/api_define_structure.js
apidoc: load parser: apidefinesuccessstructure, ./parsers/api_define_success_structure.js
apidoc: load parser: apigroupdescription, ./parsers/api_group_description.js
apidoc: load parser: apidescription, ./parsers/api_description.js
apidoc: load parser: apierror, ./parsers/api_error.js
apidoc: load parser: apierrorexample, ./parsers/api_error_example.js
apidoc: load parser: apierrorstructure, ./parsers/api_error_structure.js
apidoc: load parser: apierrortitle, ./parsers/api_error_title.js
apidoc: load parser: apiexample, ./parsers/api_example.js
apidoc: load parser: apiheader, ./parsers/api_header.js
apidoc: load parser: apiheaderexample, ./parsers/api_header_example.js
apidoc: load parser: apiheaderstructure, ./parsers/api_header_structure.js
apidoc: load parser: apiheadertitle, ./parsers/api_header_title.js
apidoc: load parser: apigroup, ./parsers/api_group.js
apidoc: load parser: apiinfo, ./parsers/api_info.js
apidoc: load parser: apiinfoexample, ./parsers/api_info_example.js
apidoc: load parser: apiinfotitle, ./parsers/api_info_title.js
apidoc: load parser: apiname, ./parsers/api_name.js
apidoc: load parser: apiparam, ./parsers/api_param.js
apidoc: load parser: apiparamtitle, ./parsers/api_param_title.js
apidoc: load parser: apipermission, ./parsers/api_permission.js
apidoc: load parser: apistructure, ./parsers/api_structure.js
apidoc: load parser: apisuccess, ./parsers/api_success.js
apidoc: load parser: apisuccessexample, ./parsers/api_success_example.js
apidoc: load parser: apisuccessstructure, ./parsers/api_success_structure.js
apidoc: load parser: apisuccesstitle, ./parsers/api_success_title.js
apidoc: load parser: apiversion, ./parsers/api_version.js
apidoc: load parser: apisamplerequest, ./parsers/api_sample_request.js
apidoc: load worker: apierrorstructure, ./workers/api_error_structure.js
apidoc: load worker: apierrortitle, ./workers/api_error_title.js
apidoc: load worker: apiheaderstructure, ./workers/api_header_structure.js
apidoc: load worker: apiheadertitle, ./workers/api_header_title.js
apidoc: load worker: apiparamtitle, ./workers/api_param_title.js
apidoc: load worker: apipermission, ./workers/api_permission.js
apidoc: load worker: apisamplerequest, ./workers/api_sample_request.js
apidoc: load worker: apistructure, ./workers/api_structure.js
apidoc: load worker: apisuccessstructure, ./workers/api_success_structure.js
apidoc: load worker: apisuccesstitle, ./workers/api_success_title.js
apidoc: load filter: apierror, ./filters/api_error.js
apidoc: load filter: apiinfo, ./filters/api_info.js
apidoc: load filter: apiparam, ./filters/api_param.js
apidoc: load filter: apisuccess, ./filters/api_success.js
apidoc: inspect file: App/Routers/users.router.php
apidoc: size: 17812
apidoc: count blocks: 17
apidoc: count elements in block 0: 477
apidoc: count elements in block 1: 69
apidoc: count elements in block 2: 32
apidoc: count elements in block 3: 30
apidoc: count elements in block 4: 46
apidoc: count elements in block 5: 8
apidoc: count elements in block 6: 41
apidoc: count elements in block 7: 81
apidoc: count elements in block 8: 41
apidoc: count elements in block 9: 47
apidoc: count elements in block 10: 123
apidoc: count elements in block 11: 46
apidoc: count elements in block 12: 70
apidoc: count elements in block 13: 80
apidoc: count elements in block 14: 59
apidoc: count elements in block 15: 56
apidoc: count elements in block 16: 51
apidoc: api found in block: 0
apidoc: parser plugin "apimethod" not found.
apidoc: parser plugin "apiroute" not found.
apidoc: parser plugin "apiparams" not found.
apidoc: parser plugin "apiparams" not found.
apidoc: parser plugin "apireturnheaders" not found.
apidoc: parser plugin "apireturn" not found.
apidoc: parse file: App/Routers/users.router.php
apidoc: No package.json found!
apidoc: read: ./apidoc.json
apidoc: create dir: public/doc/
apidoc: copy template /usr/local/lib/node_modules/apidoc/template/ to: public/doc/
apidoc: write json file: public/doc/api_data.json
apidoc: write js file: public/doc/api_data.js
apidoc: write json file: public/doc/api_project.json
apidoc: write js file: public/doc/api_project.js
Я понятия не имею, что происходит не так. Это может быть вызвано установкой «sudo»?
ах так тупо! Я должен использовать правильный синтаксис аннотации
это работает:
**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/
Других решений пока нет …