Используйте apiDoc для написания спецификаций документации API

API

Впервые опубликовано в блоге fxm5547

Подробно ознакомьтесь с официальной документацией apiDoc.

  • Подробно читайте официальную документацию:apidocjs.com

Структура файла apiDoc в проекте

  • вся рамка

    图片

  • apidoc.json

    图片

  • common.php

    • Определение общедоступной секции — разрешения (apiPermission)
      • определение
        图片
      • использовать
        图片
    • Определение общего раздела — группировка кодов состояния (apiSuccess, apiError)
      • определение
        图片
      • использовать
        图片
        图片
    • определение общедоступного раздела — ответ об ошибке (apiError, apiErrorExample)
      • определение
        图片
      • использовать
        图片

  • define.php

    • определение общедоступного раздела - группировка API
    • определение
      图片
    • использовать
      图片

Определение apidoc для конкретного интерфейса

  • Последний интерфейс определяется в реализации кода, а предыдущая версия определяется в apidoc/history.php.

  • Интерфейс определяет полный пример:

    图片

  • @apiVersion

  • В настоящее время используются только основные и второстепенные, а patch всегда равен 0.

  • @apiName

    • от@apiОпределение переводится как: как@apiза:@api {put} /user/babies/:baby_id 修改宝宝信息, но@apiNameза:@apiName put/user/babies/:baby_id, Тогда проанализированный идентификатор;put_user_babies__baby_id(Для интерфейса ORDER, отсортированного по Apidoc.json).

  • @apiGroup

    • Группировка интерфейсов, определенная вapidoc/define.php,как@apiGroup babyGroup.

  • @apiPermission

    • Разрешения интерфейса, определенные вapidoc/common.php, разрешения делятся на:
      • none: авторизация не требуется;
      • token: Требуется авторизация входа в систему пользователя, которая может быть доступен черезheader AuthorizationиCookie HBSIDперечислить;
      • admintoken: требуется авторизация администратора для входа, доступ к которой можно получить черезheader AuthorizationиCookie HBCPSIDперечислить;
      • token || admintoken: Допускается либо авторизация входа пользователя, либо авторизация входа администратора;
        图片
      • sign: требует подписи, обычно используется для взаимных вызовов между серверами, см. подробностиПодпись API HMAC-SHA1.

  • @apiDescription

    • Объясните назначение интерфейса и связанную с ним логику как можно подробнее, например:@apiDescription 使用手机号找回密码的第一步，调用该接口先验证用户输入的手机号是否已经绑定某个帐号，未绑定给出提示，已经绑定则发送验证码、重置密码.

  • @apiParam

    • Точно определить типы данных;
    • Точно определите диапазон значений, например{String{1..32}},{String{YYYY-mm-dd}},{String="0","1"};
    • Точно определите, является ли это необязательным параметром, необязательным параметром с[],как@apiParam {String} [stage];

  • @apiError

    • общедоступная ошибка, используйте напрямуюapidoc/common.phpОшибки, определенные в , такие как@apiUse InvalidToken;
    • NotFoundиValidationErrorобщедоступная ошибка определения не допускается (т.е. недоступна@apiUse), необходимо точно определить конкретные ошибки, например:
      图片

  • @apiSampleRequest

    • GET интерфейс: не писать, использовать по умолчаниюapidoc.jsonизsampleUrlАдрес запроса на автоматическую сборку
    • Другие интерфейсы:@apiSampleRequest offмы используем почтальон

группировка интерфейсов

  • Как правило, сгруппированные по функциональным модулям, одна группа соответствует одному или нескольким файлам php, и каждый файл php соответствует только одной группе;
  • Все разрешенияadmintokenинтерфейс (за исключением разрешений дляtoken || admintokenинтерфейс), размещенный в интерфейсном модулеИнтерфейс центра управлениягруппировка,admin.phpв файле;
  • Все разрешенияsignинтерфейс (кроме модуля SMS), размещенный в интерфейсном модулеВнутренний сервисный интерфейсгруппировка,internal.phpв файле;

Интерфейс управления версиями

  • В той же основной версии, только когда изменения вашего интерфейса повлияют на вызывающую сторону, вам необходимо обновить вспомогательную версию (если в модифицированной версии нет вызывающей стороны, естественно, нет необходимости обновлять версию), например, с 1.0.0 до 1.1.0.

  • При обновлении версии нужно скопировать старые комментарии apidoc вapidoc/history.php, и обновитьapiVersion

    图片

  • При обновлении основной версии интерфейса скопируйте каталог файлов старой версии как новую версию и обновите версию интерфейса (например, скопируйте v1, переименуйте ее в v2 и измените все интерфейсы в новой версии на2.0.0Версия).

  • Вызывающий может легко узнать, какие изменения были внесены в новую версию, путем сравнения версий при просмотре документа.

    图片
    图片

  • Устаревший интерфейс, маркировка@apiDeprecated, указывающий, какие интерфейсы следует использовать вместо этого:

    • Добавьте перед просроченным комментарием apidoc интерфейса:
      图片
    • Документация показывает:
      图片

генерация документа

  • На сервере DEVQA настроены запланированные задачи (crontab -lВид), документ регенерируется каждые 1 минуту.

    图片

  • При создании нового интерфейсного модуля,

    • Необходимо изменить запланированное заданиеcrontab -e;
    • Добавлена ​​навигация в шаблоне apidocvim /usr/lib/node_modules/apidoc/template/index.html;
      图片

На что следует обратить внимание при тестировании API

  • Определен ли интерфейс в строгом соответствии с этой спецификацией;
  • Обработка ошибок является всеобъемлющей, и никакие ошибки не могут быть пропущены.Неправильное сообщение должно быть кратким и четким и содержать указания, такие как "время открытия составляет 1-5 дней, пожалуйста, введите повторно";
  • В порядке ли контроль разрешений интерфейса и есть ли угроза безопасности;
  • Полностью ли согласованы интерфейсный документ и реализация; - Имя, тип, необязательные и описание параметров запроса должны быть точными и знакомыми;
  • Имена, типы и описания возвращаемых параметров должны быть точными и подробными.

Модифицированный многомодульный шаблон

Нажмите, чтобы скачать apidoc-template.zip

Категории