Документация служит всеобъемлющим руководством, объясняющим, как взаимодействовать с сервисом через API. Хорошая документация ускоряет процесс разработки, уменьшает количество ошибок и улучшает общее качество интеграции, поскольку включает в себя:
Представляем подборку лучших инструментов для создания API-документации.
Swagger
Swagger – один из самых популярных инструментов: он поддерживает много языков программирования и предоставляет удобный интерфейс для проектирования и документирования API. Swagger позволяет определять конечные точки, форматы запросов и ответов, а также методы аутентификации. Кроме того, он предоставляет интерактивные инструменты для исследования и тестирования API.
Apidog
Apidog – комплексный инструмент для разработки, документирования и управления API. Он предлагает автоматическую генерацию интерактивной документации и возможность тестирования API в реальном времени. Apidog также поддерживает генерацию кода на разных языках программирования и предоставляет широкие возможности для настройки стиля документации.
ReDoc
ReDoc – опенсорсный инструмент, поддерживающий спецификации OpenAPI 2.0 и 3.0. Он отлично подходит для публикации интерактивной API-документации и предлагает удобную навигацию с настраиваемым поиском, а также стильный, адаптивный дизайн с возможностью настройки тем.
DapperDox
DapperDox – опенсорсный OpenAPI-рендерер, совместимый с OAS 2.0 и 3.0. Он позволяет использовать контент в формате Markdown для создания диаграмм и предоставляет модуль исследования структуры API для практических экспериментов.
Theneo
Theneo – генератор документации, использующий ИИ для автоматического описания API. У него простой интерфейс, напоминающий Notion, и он поддерживает интеграции с Swagger, Postman и GitHub.
Sphinx
Sphinx – мощный генератор документации, широко используемый в Python-сообществе. Он поддерживает много языков и предлагает широкие возможности для настройки. Sphinx может генерировать документацию в разных форматах, включая HTML, PDF и ePub.
Javadoc
Javadoc специально разработан для документирования Java-кода. Он извлекает комментарии и аннотации из исходного кода для создания HTML-документации с подробным описанием классов, методов и полей.
DocFX
DocFX – генератор статических сайтов, разработанный Microsoft и с ноября 2022 года поддерживаемый сообществом .NET Foundation. Предлагает настраиваемые шаблоны для создания документации и лендингов.
Doxygen
Doxygen поддерживает C++, С, Objective-C, Python, Java, IDL, PHP, C# и Fortran, может генерировать документацию в разных форматах, включая HTML, PDF и LaTeX.
Slate
Slate фокусируется на простоте и удобстве использования, предоставляя удобный, современный, адаптивный интерфейс для API-документации. Он поддерживает Markdown, подсвечивает синтаксис больше 100 языков и предлагает интерактивную консоль для тестирования API-эндпойнтов.
Интерактивная API-документация на Slate
Docusaurus
Docusaurus предназначен для создания современной интерактивной документации и любых других статических сайтов. Он поддерживает все популярные языки, предлагает настраиваемые шаблоны, имеет встроенную функцию поиска на базе Algolia, поддержку локализации и версионирования.
Приглашаем вас на вебинар «Как меняется математика в разных индустриях: от мобильных игр к фондовым рынкам», который состоится 22 августа в 20:00 по МСК. Там вы сможете:
Узнать, как математические методы влияют на мобильные игры и фондовые рынки.
Понять различия в математических подходах в разных сферах бизнеса.
Изучить реальные кейсы применения математики в GameDev и финансах.
Оценить, какие математические знания необходимы для успешной карьеры в Data Science.
😎 Автоматизация слепых SQL-инъекций на основе логических значений
Слепая SQL-инъекция на основе логического значения (Boolean-Based Blind SQL Injection) – тип SQL-инъекции, где атакующий не видит прямого вывода SQL-запроса, но может делать выводы на основе логических (истина/ложь) ответов от приложения (эти ответы могут проявляться в виде разных кодов состояния HTTP, разного содержимого ответа или реже разных заголовков).
Анализ ответов позволяет злоумышленникам определить структуру базы данных, а в дальнейшем – буквально символ за символом выяснить, какая информация в ней содержится. Пентестеры и этичные хакеры знают, что это один из самых трудоемких типов атак для ручной эксплуатации. Но несколько простых Python-скриптов помогают полностью автоматизировать процесс:
Простейший метод – извлекать данные по одному символу, используя функции SUBSTRING() и ASCII() в MySQL. Это позволяет узнавать значение каждого символа в строке путем сравнения с ASCII-кодами.
Оптимизированный подход – использовать алгоритм бинарного поиска. Это сокращает количество запросов для определения одного символа с 96 до 7, что значительно ускоряет процесс и делает атаку менее заметной.
Дополнительные приемы для извлечения разных типов данных включают использование подзапросов для выбора данных из произвольных таблиц, объединение значений из нескольких строк в одну строку с помощью GROUP_CONCAT и преобразование разных типов данных (числа, даты и т. д.) в строки, которые легче извлечь.
Для дальнейшего ускорения процесса можно использовать многопоточность с помощью ThreadPoolExecutor из библиотеки concurrent.futures.
📶 Паттерны коммуникации в распределенных системах
Распределенные системы состоят из многих отдельных частей (или узлов), работающих вместе, но физически расположенных в разных местах. Эти части системы должны общаться друг с другом через сеть, чтобы система могла функционировать как единое целое. Хотя коммуникация критически важна, правильно ее организовать бывает непросто: разработчики иногда пытаются использовать один и тот же подход ко всем задачам коммуникации, что может быть неэффективно. Важно понимать, что существуют разные способы организации коммуникации, и выбор правильного метода зависит от конкретной задачи. Рассмотрим основные паттерны коммуникации, которые можно использовать для решения разных задач.
Запрос-ответ с HTTP
Этот синхронный паттерн коммуникации предполагает, что один сервис отправляет запрос другому сервису и ожидает ответа или ошибки, блокируя свою работу до получения результата. REST, наиболее популярный архитектурный стиль для этой модели коммуникации, использует методы протокола HTTP – GET, POST, PUT и DELETE.
Однако использование этого паттерна может привести к проблемам, если сервисы образуют цепочку взаимодействий: в таком случае сбой одного из сервисов может привести к отказу всей операции, а также к расточительному использованию ресурсов и каскадным сбоям.
Общие данные
Этот паттерн часто остается незамеченным, поскольку разработчики не всегда воспринимают его как модель коммуникации. В рамках этого подхода один компонент записывает данные в определенное место, а другой компонент считывает и обрабатывает эти данные. Например, один сервис может загрузить файл в облачное объектное хранилище (например, в корзину Amazon S3), а другой сервис затем извлекает этот файл для дальнейших действий.
Главное преимущество этого паттерна – простота реализации и возможность обеспечения взаимодействия между устаревшими и современными системами без проблем совместимости. Однако он не подходит для сценариев, требующих низкой задержки.
Асинхронный запрос-ответ
В отличие от синхронного подхода, запрос-ответ может быть реализован асинхронно и без блокировки. В этом случае получающий сервис должен явно знать место назначения для отправки ответа. Для реализации этого паттерна идеально подходят очереди сообщений, которые позволяют буферизовать несколько запросов.
Основная сложность здесь — корреляция между запросом и ответом: экземпляр сервиса, отправивший запрос, может отличаться от экземпляра, получающего ответ, поэтому требуется способ отслеживания запросов.
Коммуникация на основе событий
В этом подходе сервисы не общаются напрямую друг с другом, а генерируют события, которые могут быть использованы другими сервисами. Это требует наличия места для отправки данных о событиях и механизма, позволяющего получающим сервисам обнаруживать эти события. Брокеры сообщений, такие как RabbitMQ, могут обрабатывать оба этих аспекта. Издатели используют API для отправки событий в брокер, который управляет подписками и уведомляет подписчиков при поступлении события.
Коммуникация на основе событий
Этот паттерн идеально подходит для создания слабосвязанных взаимодействий между сервисами. Однако брокер сообщений должен обеспечивать надежную доставку событий, их упорядочивание и согласованность. Кроме того, добавляется дополнительный компонент в систему.
🛠️ Инструменты
Postgres Sandbox – ИИ-песочница для работы с PostgreSQL в браузере. Проект реализован на PGlite – легковесной версии PostgreSQL, скомпилированной в WebAssembly и упакованной в клиентскую библиотеку TypeScript. Это позволяет запускать базу данных PostgreSQL непосредственно в браузере, Node.js и Bun без необходимости устанавливать другие зависимости. Размер PGLite – всего 3 Мб после сжатия Gzip, при этом база поддерживает многие расширения PostgreSQL, включая pgvector.
textual-plotext – виджет-обертка библиотеки для построения графиков Plotext. Визуализирует данные из Python-скриптов прямо в терминале.
Такие графики можно строить прямо в терминале
BunkerWeb – опенсорсный веб-фаервол (WAF), созданный на основе NGINX. Предназначен для защиты веб-сервисов – делает их безопасными по умолчанию. Легко интегрируется в существующие среды (Linux, Docker, Swarm, Kubernetes и т. д.), полностью адаптируется под ваши специфические требования. Предоставляет удобный веб-интерфейс и систему плагинов.
Kardinal – фреймворк для создания сверхлегких временных сред разработки внутри общего кластера Kubernetes. Позволяет быстро и эффективно создавать и удалять рабочие пространства для разработки, тестирования и демонстраций, минимизируя затраты ресурсов и стоимость эксплуатации.
Viking – инструмент для управления удаленными серверами (и группами серверов) через SSH.
Terminus – опенсорсная ОС на базе Kubernetes, которая позволяет создать домашнее облако на собственном сервере. Подходит для любых задач – локального хостинга LLM, хаба по управлению IoT-девайсами, персонального репозитория или рабочего пространства.
Собственное облако Terminus
DeltaDB – легковесная, быстрая и масштабируемая база данных, созданная на основе polars и deltalake. Предназначена для разработчиков и организаций, которым нужно эффективное, простое и гибкое решение для обработки больших объемов данных с высокой скоростью и масштабируемостью.
emval – супербыстрый валидатор email-адресов для Python-приложений, написанный на Rust.
emval работает в 100–1000 раз быстрее других подобных модулей
RustPython – интерпретатор Python, написанный на Rust.
Автор рассылки: Наталья Кайда
