Dochub pdf sign edit что это
DocHub: API по-джентльменски
— Саш, админы говорят, что у нас 400 полетели адово. Глянь, в чем проблема.
— Странно… все же было хорошо.
— Коллеги, и в очередной раз у нас изменены контракты без согласования и оповещения! Это уже не первый случай! Давайте что-то с этим делать!
Решают проблему различными способами. Предлагаю рассмотреть самые (на мой взгляд) используемые.
Автогенераторы контрактов
Автогенераторов большой зоопарк. Толковых мало. Например, есть такая тулза для PHP проектов. Обычно сгенерированная документация становится доступна по некому магическому URI после деплоя.
Это решение позволяет надеяться на актуальность документации. Но, имеет ряд недостатков:
Неочевидно, где находится документация. Приходится вести реестр URI контрактов;
Документация требует сборку. Чтобы посмотреть на контракты кому-то, кроме разработчика, требуется задеплоить фичу;
Сложно отследить внесенные изменения в документацию, т.к. она каждый раз перестраивается.
В общем, решение заманчиво своей кажущейся простотой, но, к сожалению, в корне не решает проблем.
Contract first
Концептуально иной подход. Сначала создаются контракты, а затем по ним пишется код. Этот подход сам по себе прекрасен. Вот лишь некоторые профиты:
В процесс дизайна контрактов можно вовлекать несколько команд. Материал оказывается обозримым, т.е. доступен для осознания за разумный промежуток времени;
На этапе продумывания контрактов можно обнаружить логические и архитектурные ошибки. Это позволит существенно сэкономить время на разработку и повысить качество продукта;
Достигнув консенсуса по контракту, команды оказываются в едином информационном поле. Это позволяет одновременно начинать разработку как со стороны поставщика, так и со стороны потребителя.
Для заранее определенных контрактов можно в короткие сроки сделать имитаторы (замокать). Таким образом становится доступно тестирование фич потребителя еще до завершения реализации со стороны поставщика.
Заранее определенные контракты позволяют структурировать деятельность команд и повысить адекватность оценки трудозатрат.
При подходе Contract first, обычно контракты публикуются на портале разработчиков. Например, Confluence. Этот инструмент всем хорош. Он умеет версионировать документы. Фиксирует автора изменений. Умеет уведомлять об изменениях. В общем, устраняется ряд серьезных проблем.
И тут, можно было бы завершать статью, но… есть и ложка дегтя в этой бочке меда:
Толковые инструменты (например, Confluence) стоят денег. Когда речь идет о средней компании, это становится накладно.
Документ, описывающий контракты, не статичен. Он развивается. Взяв в работу документ, разработчик постоянно задает себе вопрос: «Что тут опять поменяли?». Сравнить две версии документов даже в Confluence проблема. Дело в том, что, например, Swagger-нотации не поддерживаются Confluence из коробки. Для их просмотра нужен плагин. А контент плагина сравнивать уже «больно».
Контракты как код
Выражается это в управлении архитектурными артефактами как кодовой базой. Например, описать схему можно не в MS Visio или Draw.io, а кодом PlantUML. Артефакты хранятся в репозиториях и подчиняются установленному в компании порядку работы с ними.
DocHub это один из инструментов реализующий подход ArchOps. Он рендерит контракты непосредственно из репозиториев.
Акцентирую внимание, что контракты размещаются непосредственно в кодовой базе проекта. То есть любой, кто имеет доступ к кодовой базе проекта, может вносить изменения в них. При этом, контракты являются частью процесса разработки и принимают участие в code review.
Флоу выглядит примерно так:
Флоу разделено на два этапа:
Отдельно, подробно нужно рассмотреть необходимость двух артефактов:
Профиты такого подхода:
Развитие документации идет независимо и по понятным принципам;
Изменения и история наглядны и доступны;
Контроль документации встроен в процесс разработки;
На документацию можно навесить pipeline который будет извещать заинтересованных о планах изменений в контрактах. Да, и много чего еще.
Но… как всегда есть и проблемы:
Все так же не ясно где искать документацию;
Неудобно “читать” контракты.
Именно эти две проблемы решает DocHub. Он позволяет агрегировать все контракты на одном ресурсе, а встроенный Swagger UI рендерит контракты непосредственно из GitLab.
Архитектура DocHub
DocHub глубоко интегрирован с GitLab. По сути DocHub это SPA приложение, а GitLab для него backend. Авторизация, в том числе, происходит через GitLab.
Агрегация контрактов реализована предельно просто. В каждом репозитории размещен манифест dochub.json. В нем указаны ссылки на контракты данного сервиса. DocHub проходит по репозиториям и собирает манифесты. На их основании он строит навигационное дерево. Примерно так:
Узнает он о необходимых для сканирования репозиториях из корневого манифеста. Его размещение указывается явно в настройках приложения.
Обратите внимание, что помимо рендера контрактов из GitLab, DocHub позволяет подключать внешние ресурсы по http/https. Это удобно в случае интеграции с внешними сервисами, публикующими свои контракты в нотациях Swagger. Все в одном месте.
Манифест DocHub
При загрузке дерева документов, сначала загружается корневой манифест, затем все указанные в нем манифесты проектов.
Расположение корневого манифеста указывается в настройках приложения (src/config.json).
Пример корневого манифеста (/dochub.json):
Пример манифеста проекта (/dochub.json):
Корневой манифест может содержать блок docs, но рекомендуется избегать этого. Нарушается принцип автономности проектных команд по развитию документации.
Подключаемые манифесты могут включать в себя блок imports, таким образом, подключая другие манифесты.
Одной из ключевых фич DocHub является сравнение контрактов, остановлюсь на ней подробнее.
Сравнение контрактов
Сравнение может выполняться как между ветками одного репозитория, так и между репозиториями и даже внешними источниками.
DocHub умеет сравнивать как построчно (текст), так и по сути. На картинке наглядно видно контракты, которые подверглись изменениям.
Заключение
Мы используем DocHub уже более года. Инструмент прижился. Есть амбициозные планы по его развитию. Предполагается использовать его для рендера артефактов ArchOps.
DocHub — онлайн редактор PDF
DocHub.com — онлайн-сервис для работы с PDF. Прямо из браузера вы сможете редактировать PDF, а также ставить подписи или создавать новые документы на основе обширной базы готовых шаблонов.
Ниже вы найдете подробное описание функций сервиса.
1. Редактирование PDF
• Средства для аннотаций
Подсветка или затеменнеие строк, рисование векторов и линий, добавление текстовых комментариев.
• Управление страницами
Вы можете переставить страницы местами, удалить или добавить новые страницы, а также вращать их.
• Автоматическое сохранение
Все изменения автоматически сохраняются, поэтому вам не нужно волноваться за сохранность данных.
• Работа с любыми форматами файлой
DocHub построен вокруг работы с PDF, но он также поддерживает DOC, PPT, XLS, TXT, DOCX, PPTX и множество других.
• Объединение PDF
Вы сможете соединить несколько документов в одном с помощью кнопки “Append File”.
• Работает в смартфоне
DocHub работает на мобильных платформах также хорошо, как и с компьютера. При этом не требуется установка дополнительных приложений.
• Интеграция с Google Drive и Dropbox
Сервис подключается к Gmail, Google Drive и Dropbox и позволяет управлять файлами прямо в облачной среде.
• Совместная работа над файлами
Настройте разрешения на доступ к файлу коллегам, и вы сможете коллективно работать с документами.
2. Создание PDF онлайн
Вы сможете создавать документы или формы для заполнения непосредсвтенно в браузере, а также публиковать доступ к документу в сети с гибкими настройками приватности.