Багато з нас при виконанні своїх обов'язків на роботі стикаються з необхідністю заглянути до будь-якого довідника, який дасть нам відповідь на питання. Якщо ви користувач ERP/CRM-системи, то при виниклих питаннях відразу звертаєтеся до ІТ-підтримки. Якщо ви юрист, то потребуєте у відповідному кодексі, за яким у вас виникло питання. А якщо ви займаєтеся розробкою веб-додатків для свого бізнесу або для своїх клієнтів, то вам будуть просто необхідні стандарти розробки і документація для вашого API. У кожній сфері є своя документація, з якою черпають люди інформацію, необхідну їм для виконання своєї роботи.
Здавалося б, все так просто. Але в сфері IT (Information technology) все змінюється дуже інтенсивно. Взаємозв'язки програм, додатків і т.п. через API (Application Programming Interface) теж постійно змінюються. Багато програмістів стикаються з необхідністю подивитися стандарти своєї мови програмування, API для поточного завдання, способи все це зафіксувати, щоб було простіше і комфортніше працювати через документацію надалі.
API-документація - це технічна документація, в якій фіксуються інструкції про те, як ефективно використовувати програмне API, апаратне SCPI або web API.
Для продуктів, що активно розвиваються підтримка документації API грає важливу роль, але при цьому варто не забувати про актуальність цих даних.
Один з варіантів закриття питання з документацією API може бути таким: ми беремо окремого співробітника (співробітників) для створення документації за API. Він (вони) будуть поширювати цю документацію у вигляді файлів або публікувати на сайті. Такий підхід цілком робочий, але має ряд істотних недоліків в особі людського фактора і швидкого старіння документації. Людина може щось забути, написати неправильно і т.д. Як тільки код змінився - документація застаріла. З неактуальною і помилковою документацією API-інтерфейсів розробники стикаються дуже часто. Пошуки "правди" в таких випадках збільшують трудовитрати, що в кінцевому підсумку позначається на вартості продуктів.
Так що документація API - це не тільки фіксування в документі необхідної інформації, але і підтримка її актуальності.
Припустимо, документування API було доведено до актуальності, і тепер у нас в доступі завжди безпомилкова інформація. Але, на жаль, при наявності актуальної документації труднощі не закінчуються. API, що вийшло може бути настільки складним і незручним, що робота з ним може стати кошмаром. Адже в першу чергу працювати з ним будуть люди, а вже тільки потім програма. Очевидно, що потрібен якийсь стандарт розробки API , щоб розробники навіть при побіжному ознайомленні розуміли, як з ним коректно взаємодіяти. Також наявність стандарту API дозволяє використовувати кошти автоматичної кодогенераціі, що істотно підвищує швидкість розробки.
Перш ніж перейти до вирішення виниклих проблем, необхідно знати існуючі протоколи реалізації веб-сервісів, як вони працюють, їх особливості. А також познайомитися з різними інструментами для стандартизації API-інтерфейсів.
У веб-розробці активно використовуються веб-інтерфейси або web API. У міру розвитку інтернет-систем одні web API застарівають, як, наприклад, SOAP (Simple Object Access Protocol) , а інші користуються великим попитом, як, наприклад, REST (Representational state transfer) . А також можна зустріти і "темну конячку" GraphQL , яку запустив Facebook в 2015 році. Нижче наведені схеми веб-сервісів API.
Мал 1. REST веб сервіс
Мал 2. GraphQL веб сервіс
Налагодити узгоджену комунікацію між усіма видами клієнтів і серверним додатком буває непросто. Частково ця проблема вирішується базовими положеннями REST архітектури (або будь-якою іншою архітектурою, яку ви виберете), проте без опису інтерфейсу сервера (API) не обійтися. Іншими словами, розробники клієнтських додатків повинні якимось чином розуміти, як їм можна взаємодіяти з серверним додатком, яке це вплине і що вони отримають в результаті.
Один з найпопулярніших на даний момент способів опису API - це специфікація Swagger . Swagger - це не тільки специфікація, але ще і ціла екосистема для вирішення різноманітних завдань з документування API.
Список специфікацій для документації RESTful API:
Рішенням перерахованих вище труднощів при документуванні API може стати генерація автодокументаціі , тобто при зміні коду програми документація автоматично перебудовується з урахуванням цих змін. Таким чином, усувається і людський фактор, і проблема неактуальності. Звичайно, цей спосіб вимагає певних витрат на початковому етапі. Необхідно налаштувати систему генерації API-документації, а також розробити і дотримуватися набору правил при написанні коду.
При розробці власних веб-сервісів і при зіткненні з подібними проблемами в документуванні API наші розробники знайшли цікаве рішення, описане далі. Отже, яким чином ми виконали документування REST API?
При розробці веб-додатків ми використовуємо підхід REST для реалізації серверної частини програми. Цей підхід дозволяє легко додавати нові види клієнтських додатків, які повинні працювати з основною бізнес-логікою програми. Наприклад, на початковому етапі можна обмежитися використанням браузера в якості платформи для реалізації призначеного для користувача інтерфейсу, а в подальшому додати додатки для смартфонів або настільних комп'ютерів під управлінням різних операційних систем. А так як концепція IoT (Internet of Things або Інтернет речей) набирає обертів, то клієнтом нашого застосування може бути не тільки людина, але і будь-який пристрій. Імовірність того, що доведеться переписувати все через те, що користувачі стали віддавати перевагу одній мобільній платформі замість іншій, значно зменшується. Тепер досить реалізувати клієнта для нової платформи. Не треба витрачати ресурси на переробку основного функціоналу, який вже протестований і добре працює.
При розробці нашого продукту SaaS Solutions ми реалізували RESTful веб-сервіс і додаток для роботи в браузері з використанням зв'язки технологій .Net Framework + Asp Net Web Api + Angular.js . Для генерації документації скористалися бібліотекою Swashbuckle , яка реалізує генерацію документації з специфікації Swagger для .Net-рішень.
В результаті вийшла ось така веб-сторінка з описом API.
Мал. 3 Приклад Мал. 3 Приклад документації API, згенерованого бібліотекою Swashbuckle.
Це не просто сторінка, що описує API, вона також дає можливість протестувати роботу API без використання сторонніх коштів.
Мал 4. Web API Мал. 4 Web API документація з висновком результату роботи API
Наведена вище як приклад документація web API демонструє, що навіть в стадії розробки вона вже придатна для внутрішнього використання. Її наявність значно спростило взаємодію між командами, які розробляють серверний та клієнтський додатки. Після додавання описів роботи методів і форматів значень, що повертаються її можна буде застосовувати і для зовнішнього використання.
SaaS сервіси
Програми 1С:Підприємство
CRM
ERP
Node.JS, .NET
1С:Підприємство
API, IPasS
Разработка Web Apps
1С:Підприємство Автоматизація
Аудит IT проектів
Інтеграція 1С:Підприємство
Отримуйте наші інформаційні матеріали:
Працюємо на IT-ринку з 2008 року.
Наша місія - спростити управління даними.
Copyright © 2008-2025 TQMsystems. Всі права захищені. Privacy Policy | Terms of Service