Я хотел бы рассказать вам об утилите, с которой вы сможете забыть о боли создания документации для Web API. О том как это сделать прошу всех под кат.
Итак, добро пожаловать под кат, {username}! Ты возможно спросишь с помощью чего так красиво получается? Ответ: apiDoc. Что еще за apiDoc? apiDoc — это утилита для генерации документации основываясь на комментариях в коде. Но с одной оговоркой, эти комментарии должны быть определенного вида. Можно создавать документацию для проектов на: C#, Dart, Erlang, Go, Java, Javascript, PHP, Python, Ruby, Perl и прочих. Но в этой статье я расскажу как сделать такую красивую документацию на основе проекта на Python.
Для этого вам понадобится:
- Node.js(с npm)
- Проект который нужно задокументировать
- Немного свободного времени
Установка Node.js
Те у кого установлен пакет с Node.js, пропустите данный пункт но убедитесь что у вас работает npm. А остальные должны скачать с сайта nodejs.org инсталлятор и установить его. Проследите чтобы Node.js попал в переменную $PATH. Пример установщика для Mac OS X:
Установка apiDoc
Надеюсь все справились с установкой Node.JS и мы можем перейти далее. Для установки apiDoc откройте терминал (командную строку в Windows) и запустите команду:
sudo npm install -g apidoc
И на выходе вы должны получить что-то вроде этого.
Подготовка к созданию документации
Ну вот мы и добрались до создания документации. Для того чтобы сгенерировать документацию необходимо сделать комментарии в коде. Вот пример комментария в коде.
""" @api {get} /2/get_news?offset=:offset&count=:count Получение новостей @apiName GetNews @apiGroup News @apiVersion 0.2.0 @apiParam {String} [count=5] Количество новостей @apiParam {String} [offset=0] Кол-во пропущенных новостей с начала """
Что есть что? Приведу описание некоторых основных «тегов» для генерирования документации. Все теги можно посмотреть здесь.
@api
Обязательный тег для генерации документации.
@api {method} path [title]
method — типа запроса (GET,POST,PUT и т.д.)
path — путь до метода например /2/get_news
title — название метода которое будет отображаться в документации
Пример использования:
""" @api {get} /user/:id """
@apiName
Тег определяющий название блока документации. Рекомендуется всегда использовать.
@apiName name
name — название метода
Пример использования:
""" @apiName GetNews """
@apiGroup
Тег связывающий блоки документации в одну группу на сайте документации.
@apiGroup name
name — название группы
Пример использования:
""" @apiGroup News """
@apiVersion
Тег используется для определения версии метода.
![](https://habrastorage.org/files/ff8/a13/20f/ff8a1320f978456c9d67617c9e054343.png)
@apiVersion version
version — версия метода согласно семантическому версионированию подробнее по ссылке здесь.
Пример использования:
""" @apiVersion 0.2.0 """
@apiParam
Тег используется для описания параметра передаваемого в метод
Использование:
@apiParam [{type}] [field=defaultValue] [description]
type — тип объекта({Boolean}, {Number}, {String}, {Object}, {String[]} и прочие)
field — название параметра и опционально можно задать значение по умолчанию указав равно после названия параметра
description — описание параметра
Пример использования:
""" @apiParam {String} [count=5] Количество новостей """
@apiSuccess
Тег используется для описания параметра передаваемого в метод
@apiSuccess [{type}] field [description]
type — тип объекта({Boolean}, {Number}, {String}, {Object}, {String[]} и прочие)
field — название объекта который будет получен после запроса
description — описание этого объекта
Пример использования:
""" @api {get} /user/:id @apiSuccess {String} firstname Firstname of the User. @apiSuccess {String} lastname Lastname of the User. """
Изготовление документации
Итак, после краткого введения в теги apiDoc можно попробовать создать документацию, для этого нужно подготовить поле действий. Для этого положите в корень файл конфигурации apidoc.json.
{ "name": "Мой НГТУ", //Название проекта "version": "0.2.0", //Текущая версия API(будет сравниваться с предыдущими) "description": "Мой НГТУ - облачная студенческая платформа", //Описание проекта "title": "Документация API Мой НГТУ", //Название страницы API "url" : "https://api.mynstu.me", //Расположение Web API "sampleUrl": "https://api.mynstu.me", //Расположение Web API "template": { //Конфигурация шаблона "withCompare": true, //Включаем сравнение "withGenerator": true // Ну и то что будет генерировать apiDoc } }
Далее для генерации следует запустить команду:
apidoc
На выходе вы получите это:
Документацию можно забрать в папке doc которая лежит в корне вашего проекта. Чтобы посмотреть результат откройте index.html.
Итоги
У нас получилось сделать практичную и красивую документацию. Вот как она выглядит:
Посмотреть как она выглядит полностью и понажимать на кнопочки можно здесь.
ссылка на оригинал статьи http://habrahabr.ru/post/262813/
Добавить комментарий