/*= @group Название группы - Описание группы */
/*= @interface */
interface File {
path: string;
size: number,
isDir: boolean
}
/*=
* @schema CustomError {
* code {#number};
* message {#string}
* } - Описание схемы ошибки
*/
/*=
* @name Роут для тестов
* @desc Ваше описание роута
*
* @path /path/to/{route}?={id}
* @type POST
*
* @param route - Ваше описание
* @query id {#number}
* @permissions TEST_1, TEST_2
*
* @header Authorization {#string} - Ключ авторизации
* @header Optional-Header? {#your_custom_type} - Поддержка нескольких Header-ов
*
* @body {
* id? {#number} - Опциональное поле;
* test {
* test2 {#number | #string} - Поддержка нескольких типов;
* id {#number}
* }
* }
*
* @error 10013 { #CustomError } - Код ошибки, тип и описание
* @success 20001 {
* files { #File[] } - Массивы
* } - Код успешного запроса, тип и описание
*/- OADP* - это аббривеатура Obvilion API Docs Parser
OADP использует многострочный комментарий с определенным префиксом (по умолчанию =), его можно легко изменить в конфиге.
Кроме этого поддерживаются блоки с кодом как и со звездочками на каждой новой строке, так и без них.
/*=
* @аргумент имя {тип} - описание
*/Строку в вышеуказанном коде мы можем разбить на четыре части:
@аргумент, он обязательно должен начинаться с символа@. Этот аргумент указывает, за что отвечает следующая строка кода. Не может содержать пробелов.имянеобходим, для того чтобы указывать некоторый текст в наш блок кода. Обычно используется для указания названия обьекта.{тип}находится в фигурных скобках, и обозначает обьект или его тип. О типах мы поговорим ниже.- описаниепишется после символа-, может содержать множество слов. Есть поддержка форматирования текста.
/*=
* @body {
* id? {#number} - Опциональное поле;
* test {
* test2 {#number | #string} - Поддержка нескольких типов;
* id {#CustomSchema}
* }
* }
*/- Давайте теперь разберём создание обьектов. В данном случае мы указываем, что в
bodyнужно использовать данный JSON обьект. Внутри фигурных скобок мы видим множество других переменных. - Знак вопроса
?в конце названия переменной означает, что данная переменная не является обязательной и отутствие данного значения в вашем API не будет восприниматься как ошибка. - Все конечные типы должны записываться с знаком решетки
#перед названием типа. Имеется поддержка нескольких типов через разграничивающий символ| - Далее идет описание, оно является опциональным, и его писать не обязательно.
- Обратите внимание, что все обьявленные значения должны заканчиваться разграничительным символом
;, за исключением последнего значения в блоке фигурных скобок{}
| Аргумент | Описание | Флаги |
|---|---|---|
@interface |
Вы можете преобразовать ваш interface, написанный на языке TypeScript в схему | - |
@schema |
Преобразует блок документации в схему | <name> <type> [description] |
@group |
Создает группу запросов с указанным именем и описанием. Можно использовать несколько раз в одном файле. | <name> [description] |
@name |
Устанавливает название тестируемому запросу | <name> |
@desc |
Устанавливает описание тестируемому запросу | <name> |
@path |
Устанавливает путь URL к тестируемому запросу | <name> |
@param |
Устанавливает свойтва параметра в пути URL запроса | <name> [type] [description] |
@query |
Устанавливает свойтва query-парметра в пути URL запроса | <name> [type] [description] |
@type |
Устанавливает метод запроса (GET, POST, DELETE...) | <name> |
@body |
Устанавливает обьект в body запроса | <type> |
@header |
Добавляет в запрос header | <name> [type] [description] |
@permissions |
Устанавливает необходимые permissions для выполнения запроса | <name> |
@error |
Указывает обьект, который возращается при ошибке выполнения запроса. Можно использовать несколько раз. | <name> [type] [description] |
@success |
Указывает обьект, который возращается при успешном выполнении запроса. Можно использовать несколько раз. | <name> [type] [description] |