[Из песочницы] Как сделать красивую документацию для Web API, за которую будет не стыдно16.07.2015 19:03

Я хотел бы рассказать вам об утилите, с которой вы сможете забыть о боли создания документации для 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]

"""
@api {get} /user/:id
"""

@apiName

Тег определяющий название блока документации. Рекомендуется всегда использовать.

@apiName name

"""
@apiName GetNews
"""

@apiGroup

Тег связывающий блоки документации в одну группу на сайте документации.

@apiGroup name

"""
@apiGroup News
"""

@apiVersion

Тег используется для определения версии метода.

Результат версионирования:

@apiVersion version

"""
@apiVersion 0.2.0
"""

@apiParam [{type}] [field=defaultValue] [description]

"""
@apiParam {String} [count=5] Количество новостей
"""

@apiSuccess

Тег используется для описания параметра передаваемого в метод

@apiSuccess [{type}] 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.

Итоги

У нас получилось сделать практичную и красивую документацию. Вот как она выглядит:

Посмотреть как она выглядит полностью и понажимать на кнопочки можно здесь.

© Habrahabr.ru