RESTful Visual Editor



Всім привіт!
Хочу представити вам власну розробку API для створення документації. Вона ще трохи «сира», оскільки я приділив їй всього тиждень, крім того, я не є веб-розробником. Однак на даному етапі, з метою написання API-документації для свого майбутнього проекту, вона мене повністю влаштовує.

Сама розробка знаходиться на GitHub: github.com/gatools/restful-visual-editor

Зацікавилися — ласкаво прошу під кат.


Трохи передісторії
Спочатку у мене не було в планах писати якийсь редактор документації для API. Стояв вибір писати в Markdown або в RAML. Markdown відпав відразу ж, оскільки в цих цілях він не особливо зручний для мене. Тому вибір припав на RAML, адже до нього є цікавий конвертер raml2html. Потренувавшись працювати в ньому, я прийшов до висновку, що не хочу писати документацію мовою YAML. І тут з'явилася ідея створити візуальний редактор, в якому я можу просто і зручно заповнити потрібні поля. В інтернеті є різні комерційні редактори, але безкоштовних серед них я не знайшов.

Редактор
Після створення проекту на початковому екрані вводимо основну інформацію, а саме: версія документації, посилання на сервер і опис.


У розділі документації можна додати додаткові анотації до проекту. Для зручності я додав SimpleMDE редактор.


І нарешті, основна частина — це шляху і робота з ними:


Тут можна додати тип запиту, опис хедерів, обов'язкові та необов'язкові параметри, приклад використання і відповіді від сервера.

Трохи про коді і структурі
Редактор складається з двох частин: сервер Node.JS, який забезпечує роботу з файлами, і веб-клієнт, усередині якого відбувається формування проекту у форматі JSON.

У серверній частині коду нічого особливого — звичайний веб-сервер з парою функцій для ajax-запитів.

Клієнтська частина трохи складніше. Є основний екран, який через ajax-запити довантажує інші екрани (subview). Виглядає це так:
/* Show documentation view for specified index */
function showDocumentationView(event) {
$("#content").empty();
currentDocumentationIndex = event.data.index;

if (currentDocumentationIndex < 0) return;

$("#content").load("view/documentation-view.html", (response, status, xhr) => {
if (status == "error") alert("Somthing was wrong, check Node.Js logs");
});
}

/* Show reference view for specified index */
function showReferenceView(event) {
$("#content").empty();
currentReferenceIndex = event.data.index;

if (currentReferenceIndex < 0) return;

$("#content").load("view/reference-view.html", (response, status, xhr) => {
if (status == "error") alert("Somthing was wrong, check Node.Js logs");
});
}

В редакторі проекту використовуються чотири (на даний момент) основних глобальних змінних:
projectRootObject = {};
projectFileName = "";
сurrentDocumentationIndex = -1;
currentReferenceIndex = -1;

Завдяки цим змінним подгруженные екрани можуть знати, яку частину даних ним завантажити і переглянути.

Плани на майбутнє
  • можливість конвертування проекту в RAML і Swagger
  • співавторство
  • експорт в HTML
  • порівняння версій


Установка
Для роботи необхідно встановити Node.JS завантажити його можна з офіційного сайту.

Далі завантажуємо з репозиторію сам редактор і встановлюємо залежності:
git clone https://github.com/gatools/restful-visual-editor.git
 
cd restful-visual-editor
 
npm install
 

Для запуску використовуємо команду:
node app.js
 

Після запуску відкриваємо в браузері:
http://localhost:3000

Ось в принципі і все. Дякую за увагу до моєї статті. Буду радий дізнатися ваші думки! А також пишіть свої зауваження та пропозиції по удосконаленню даної розробки.

Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.