tmsApiDoc
Что это такое?
tmsApiDoc - простой инструмент быстрого создания документации по API как для разработчиков так и для заказчиков. Позволяет с использованием минимальных средств (блокнот, vi... ) и нехитрого набора из нескольких правил создавать форматированное структурированное описание API и его методов.
При работе не требуется изучать сложный синтаксис, не требуются wysiwyg редакторы или офисные пакеты. Не требуется СУБД. Содержимое лежит в файлах и можно с легкостью осуществлять версионирование и просмотр изменений.
Правила и синтаксис
В каталоге, в котором планируется описывать API создается по одному файлу на один метод API. Правил именования файлов нет.
Для описания метода, как правило, информация делится на блоки, описывающие адрес ресурса, передаваемые параметры, ответы...
С этой целью в tmsApiDoc есть набор блоков:
- :TITLE: - блок дает название методу и кратко его описывает
- :DESCRIPTION: - развернутое описание основного функционала
- :URL: - адрес ресурса, по которому следует отправлять запросы
- :METHOD: - метод доступе к ресурсу [GET | POST ... ]
- :HEADERS: - заголовки запроса, отсылаемые на сервер
- :RESPONSEHEADERS: - заголовки возвращаемые сервером
- :GET: - описание параметров, передаваемых методом GET
- :POST: - Описание параметров, передаваемых методу API
- :ERRORS: - Описание ошибок, которые может генериировать метод
- :INPUT: - примеры запросов к ресурсу
- :OUTPUT: - примеры ответов ресурса
Информация в файле представляется в виде последовательного черодования строк со служебными маркерами и непосредственно данных.
Для того чтобы инициализировать любой блок достаточно на новой строке написать его сигнатуру. Все что будет размещаться в файле строкой ниже сигнатуры автоматически попадает в блок.
Пример:
:DESCRIPTION:
1 строка описания
2 строка описания
....
Служебные символы:
; - наличие данного символа в начале строки указвыает, что строка закомментирована. Строка не будет участвовать в выводе итоговых данных
| - наличие символа указывает на необходимость добавления в текущем месте пустой строки в итоговом выводе. Все пустые строки исходного файла игнорируются при выводе итогового описания
Нужно помнить, что блок :URL: однострочный блок, указывающий только адрес ресурса Все блоки кроме :URL: могут содержать текстовые данные (текст со вставками html-верстки при необходимости). Допускается использование дополнительных маркеров {JSON}{/JSON} {XML}{/XML} {PHP}{/PHP}
Для отображения структурированного и подсвеченного JSON кода его нужно заключить в блоки следующим образом
{JSON}
....
{/JSON}
Для отображения структурированного и подсвеченного XML кода его нужно заключить в блоки следующим образом
{XML}
....
{/XML}
Для отображения структурированного и подсвеченного PHP кода его нужно заключить в блоки следующим образом
{PHP}
....
{/PHP}