Статьи

Создание документации API для внешних и внутренних пользователей.

В крупных интеграционных проектах постоянно возникает необходимость в создании документации API для пользователей, принадлежащих к разным, но связанным целевым группам. Читайте дальше, чтобы узнать, как генерировать спецификации API на основе Zato для нескольких групп из одного источника информации.

Типичным сценарием является предоставление доступа к одним и тем же API внешним и внутренним пользователям — их объединяет то, что все они могут хотеть получить доступ к одним и тем же API, но не все из них должны иметь доступ к документации с одинаковым уровнем детализации.

Например, внешние разработчики должны знать только, для чего предназначена конкретная конечная точка и как ее использовать, но внутренним также может быть предоставлена ​​информация о ее внутренней работе, о типе деталей, о которой внешние пользователи никогда не должны узнавать.

Если документация для двух таких групп хранится отдельно, для этого может потребоваться больше усилий по обслуживанию, чем необходимо — в конце концов, если большая часть из них одинакова для всех, то имеет смысл хранить ее в одном месте и только добавлять или удалять детали, в зависимости от для какой группы должна быть создана конкретная документация по API.

В предыдущей статье шаг за шагом проходил процесс создания спецификаций API — этот шаг идет еще дальше, добавляя понятие тегов , определяющих , какие части документации генерировать или нет.

Python Docstrings

Давайте использовать один из тех же сервисов, что и раньше — вот его основная форма:


Джава