После написания апи-интерфейса нужно написать апи-документ, если очень хлопотно писать по одному, то приходится использовать апидок, чтобы быстро сгенерировать документ только написав комментарии.
Установить
Первый шаг — установить глобальный модуль apidoc.
npm install apidoc -g
Изменить аннотацию интерфейса
Найдите файл index.js в маршрутах проекта романа-api и измените комментарий следующим образом.
/**
* @api {get} /index 请求首页数据
* @apiVersion 1.0.0
* @apiName 获取首页数据
* @apiGroup index
*
*
* @apiSuccess {Number} flag 是否获取到数据 1成功 0失败
* @apiSuccess {Array} books 返回书籍内容
* @apiSuccess {String} msg 返回信息
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "flag": 1,
* "books": [
* {
* "_id": "5816b415b06d1d32157790b1",
* "title": "圣墟",
* "author": "辰东",
* "shortIntro": "在破败中崛起，在寂灭中复苏。沧海成尘，雷电枯竭，那一缕幽雾又一次临近大地，世间的枷锁被打开了，一个全新的世界就此揭开神秘的一角……",
* "cover": "http://statics.zhuishushenqi.com/agent/http%3A%2F%2Fimg.1391.com%2Fapi%2Fv1%2Fbookcenter%2Fcover%2F1%2F1228859%2F1228859_fac7917a960547eb953edf0b740cef3a.jpg%2F",
* "site": "zhuishuvip",
* "majorCate": "玄幻",
* "minorCate": "东方玄幻",
* "allowMonthly": false,
* "banned": 0,
* "latelyFollower": 283375,
* "retentionRatio": "73.42"
* }
* ],
* "msg": "OK"
* }
*
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* { "flag": 0, "msg": "rankingId有问题" }
*/
@api {метод} путь [название] @api проигнорирует этот комментарий без @api apidoc метод запрошенный метод путь путь титул титул
версия @apiVersion Устанавливает версию блока документации. версия номер версии
@apiName имя Определяет имя блока документации метода. Имя будет использоваться для поднавигации в сгенерированном выводе. назовите имя метода
@apiимя группы Определяет, к какой группе относится блок документации метода. Группы будут использоваться для основной навигации в сгенерированном выводе. имя Имя группы. Также используется в качестве навигационного названия.
@apiSuccess [(группа)] [{тип}] поле [описание] Успешно возвращает параметры. (группа) необязательный Все параметры будут сгруппированы по этому имени. Нет групп, настройки по умолчанию Success 200. {type} необязательный возвращаемый тип поле возвращает идентификатор описание
@apiParamExample [{тип}] [название] пример Пример запроса параметров. {тип} необязательный формат ответа короткое имя для примера заголовка пример подробный пример
@apiErrorExample [{тип}] [название] пример Пример сообщения об ошибке, выводимого в виде предварительно отформатированного кода. {тип} необязательный формат ответа короткое имя для примера заголовка пример подробный пример
настроить документ запуска npm
Откройте файл package.json и добавьте конфигурацию команды doc.
"doc": "apidoc -i routes/ -o public/"
route/ Папка для вывода документации по API. public/ Выводит документы в общую папку, а не в созданную автоматически. Выполнить документ запуска npm Посетите http://localhost:3000/, чтобы просмотреть сгенерированную документацию по API.