Оригинальный адрес:Блог Лян Гуйчжао
В процессе разработки на стороне сервера нам необходимо предоставить документ интерфейса API для использования в Интернете и на мобильных устройствах. Существует много способов реализовать работу по написанию документов интерфейса API, например, написание через документы Word или обслуживание через MediaWiki. Кроме того, существует более популярный способ использования Swagger для автоматического создания документации. Здесь я хотел бы поделиться еще одним инструментом для создания документации по веб-API apidoc.
apidoc создает документацию по веб-API с помощью комментариев в исходном коде. Поэтому apidoc может не вмешиваться в существующий код. Кроме того, apidoc может поддерживать несколько языков C#, Go, Dart, Java, JavaScript, PHP, TypeScript (все языки, поддерживающие DocStyle), CoffeeScript, Erlang, Perl, Python, Ruby, Lua. Очень удобно создавать интерактивные страницы документации через apidoc.
Начать
Во-первых, нам нужна поддержка node.js. После настройки среды node.js введите имя npm через терминал для установки.
npm install apidoc -g
Далее нам также нужно добавить файл apidoc.json в корневой каталог проекта проекта.
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
Здесь автор в основном демонстрирует, как аннотации Java можно использовать в сочетании с apidoc. Теперь давайте сначала рассмотрим случай.
/**
* @api {GET} logistics/policys 查询签收预警策略
* @apiDescription 查询签收预警策略
* @apiGroup QUERY
* @apiName logistics/policys
* @apiParam {Integer} edition 平台类型
* @apiParam {String} tenantCode 商家名称
* @apiPermission LOGISTICS_POCILY
*/
Наконец, мы вводим команду apidoc в терминал для создания документации. Здесь мы заменяем myapp/ на корневую директорию нашего собственного проекта, а apidoc/ на адрес, по которому необходимо сгенерировать документацию.
apidoc -i myapp/ -o apidoc/
Например, у автора конфигурация такая.
apidoc -i /Users/lianggzone/Documents/dev-space/git-repo -o /Users/lianggzone/Documents/dev-space/apidoc/
комментарии к коду
@api
Тег @api является обязательным, и только блоки комментариев, использующие тег @api, будут анализироваться для создания содержимого документации. Формат следующий:
@api {method} path [title]
Здесь необходимо пояснить содержание параметров.
| имя параметра | описывать |
|---|---|
| method | Методы запроса, такие как POST, GET, POST, PUT, DELETE и т. д. |
| path | путь запроса. |
| название【необязательный】 | простое описание |
@apiDescription
@apiDescription описывает интерфейс API. Формат следующий:
@apiDescription text
@apiGroup
@apiGroup представляет имя группы, которое будет преобразовано в меню панели навигации первого уровня. Формат следующий:
@apiGroup name
@apiName
@apiName представляет имя интерфейса. Обратите внимание, что в рамках той же @apiGroup @api с таким же именем отличается @apiVersion, иначе @api перезапишет ранее определенный @api. Формат следующий:
@apiName name
@apiVersion
@apiVersion представляет собой версию интерфейса, используемую вместе с @apiName. Формат следующий:
@apiVersion version
@apiParam
@apiParam определяет параметры запроса, требуемые интерфейсом API. Формат следующий:
@apiParam [(group)] [{type}] [field=defaultValue] [description]
Здесь необходимо пояснить содержание параметров.
| имя параметра | описывать |
|---|---|
| (группа)【Необязательно】 | группировка параметров |
| {тип}【необязательный】 | Тип параметра, включая {Boolean}, {Number}, {String}, {Object}, {String[]}, (массив строк),... |
| {тип{размер}}【необязательно】 | Диапазоны параметров могут быть объявлены, например, {string{..5}}, {string{2..5}}, {number{100-999}} |
| {type=allowedValues}【необязательный】 | Допустимые значения перечисления для параметров могут быть объявлены, например, {string="small","huge"}, {number=1,2,3,99} |
| field | имя параметра |
| [field] | объявить параметр необязательным |
| = значение по умолчанию [необязательно] | объявить значение параметра по умолчанию |
| Описание (необязательно】 | объявить описание параметра |
Аналогичное использование, есть @apiHeader для определения заголовка запроса, требуемого интерфейсом API, @apiSuccess для определения ответа, требуемого интерфейсом API для успешного выполнения, и @apiError для определения ошибки ответа, требуемой интерфейсом API.
Здесь мы рассматриваем случай.
/**
* @apiParam {Integer} edition=1 平台类型
* @apiParam {String} [tenantCode] 商家名称
*/
Кроме того, существуют @apiParamExample, @apiHeaderExample, @apiErrorExample, @apiSuccessExample, которые можно использовать для предоставления соответствующих примеров в документации.
@apiPermission
@apiPermission определяет точки разрешений, необходимые интерфейсу API. Формат следующий:
@apiPermission name
Кроме того, есть специальные аннотации. Например, @apiDeprecated указывает, что этот интерфейс API устарел, а @apiIgnore указывает, что разрешение этого интерфейса игнорируется. Для получения дополнительной информации об использовании вы можете прочитать официальную документацию: http://apidocjs.com/#demo
полное дело
Наконец, мы используем официальный случай, чтобы объяснить следующую полную конфигурацию.
Сначала настройте apidoc.json со следующим содержимым:
{
"name": "example",
"version": "0.1.0",
"description": "A basic apiDoc example"
}
Затем мы настраиваем соответствующие аннотации исходного кода Java.
/**
* @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.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
Затем выполните присвоение имен для создания документации.
apidoc -i myapp/ -o apidoc/
Получившаяся страница показана ниже.
(Заканчивать)
Другие интересные статьи можно найти в общедоступном аккаунте WeChat «Server Thinking»!