Многие из нас при выполнении своих обязанностей на работе сталкиваются с необходимостью заглянуть в какой-либо справочник, который даст нам ответ на вопрос. Если вы пользователь ERP / CRM-системы, то при возникших вопросах сразу обращаетесь в ИТ-поддержку. Если вы юрист, то нуждаетесь в соответствующем кодексе, по которому у вас возник вопрос. А если вы занимаетесь разработкой веб-приложений для своего бизнеса или для своих клиентов, то вам будут просто необходимы стандарты разработки и документация для вашего API. В каждой сфере есть своя документация, из которой черпают люди информацию, необходимую им для выполнения своей работы.
Казалось бы, всё так просто. Но в сфере IT (Information technology) всё меняется очень интенсивно. Взаимосвязи программ, приложений и т.п. через API (Application Programming Interface) тоже постоянно меняются. Многие программисты сталкиваются с необходимостью посмотреть стандарты своего языка программирования, API для текущей задачи, способы все это зафиксировать, чтоб было проще и комфортнее работать через документацию в дальнейшем.
Проблема документирования API
API-документация - это техническая документация, в которой фиксируются инструкции о том, как эффективно использовать программное API, аппаратное SCPI или web API.
Для активно развивающихся продуктов поддержка документации API играет немаловажную роль, но при этом стоит не забывать об актуальности этих данных.
Один из вариантов закрытия вопроса с документацией API может быть такой: мы берем отдельного сотрудника (сотрудников) для создания документации по 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-архитектуры
Наладить согласованную коммуникацию между всеми видами клиентов и серверным приложением бывает непросто. Отчасти эта проблема решается базовыми положениями REST архитектуры (или любой другой архитектурой, которую вы выберете), тем не менее без описания интерфейса сервера (API) не обойтись. Другими словами, разработчики клиентских приложений должны каким-то образом понимать, как им можно взаимодействовать с серверным приложением, какое это окажет влияние и что они получат в результате.
Один из самых популярных на данный момент способов описания API - это спецификация Swagger. Swagger - это не только спецификация, но еще и целая экосистема для решения разнообразных задач по документированию API.
Список спецификаций для документации RESTful API:
Автогенерация - наше всё
Решением вышеперечисленных трудностей при документировании API может стать генерация автодокументации, т.е. при изменении кода приложения документация автоматически перестраивается с учетом этих изменений. Таким образом, устраняется и человеческий фактор, и проблема неактуальности. Конечно, этот способ требует определенных затрат на начальном этапе. Необходимо настроить систему генерации API-документации, а также разработать и придерживаться набора правил при написании кода.
Кейс TQM Systems: решаем задачу документации REST API
При разработке собственных веб-сервисов и при столкновении с подобными проблемами в документировании API наши разработчики нашли интересное решение, описанное далее. Итак, каким образом мы выполнили документирование REST API?
Почему REST API
При разработке веб-приложений мы используем подход REST для реализации серверной части приложения. Этот подход позволяет легко добавлять новые виды клиентских приложений, которые должны работать с основной бизнес-логикой приложения. Например, на начальном этапе можно ограничиться использованием браузера в качестве платформы для реализации пользовательского интерфейса, а в дальнейшем добавить приложения для смартфонов или настольных компьютеров под управлением различных операционных систем. А так как концепция IoT (Internet of Things или Интернет вещей) набирает обороты, то клиентом нашего приложения может быть не только человек, но и любое устройство. Вероятность того, что придется переписывать все из-за того, что пользователи стали предпочитать одну мобильную платформу другой, значительно уменьшается. Теперь достаточно реализовать клиента для новой платформы. Не надо тратить ресурсы на переработку основного функционала, который уже протестирован и хорошо работает.
Как документировать REST API
При разработке нашего продукта SaaS Solutions мы реализовали RESTful веб-сервис и приложение для работы в браузере с использованием связки технологий .Net Framework + Asp Net Web Api + Angular.js. Для генерации документации воспользовались библиотекой Swashbuckle, которая реализует генерацию документации по спецификации Swagger для .Net-решений.
Пример готовой документации API
В результате получилась вот такая веб-страница с описанием 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-2024 TQMsystems. Все права защищены. Privacy Policy | Terms of Service