В крупных интеграционных проектах постоянно возникает необходимость в создании документации API для пользователей, принадлежащих к разным, но связанным целевым группам. Читайте дальше, чтобы узнать, как генерировать спецификации API на основе Zato для нескольких групп из одного источника информации.
Типичным сценарием является предоставление доступа к одним и тем же API внешним и внутренним пользователям — их объединяет то, что все они могут хотеть получить доступ к одним и тем же API, но не все из них должны иметь доступ к документации с одинаковым уровнем детализации.
Например, внешние разработчики должны знать только, для чего предназначена конкретная конечная точка и как ее использовать, но внутренним также может быть предоставлена информация о ее внутренней работе, о типе деталей, о которой внешние пользователи никогда не должны узнавать.
Если документация для двух таких групп хранится отдельно, для этого может потребоваться больше усилий по обслуживанию, чем необходимо — в конце концов, если большая часть из них одинакова для всех, то имеет смысл хранить ее в одном месте и только добавлять или удалять детали, в зависимости от для какой группы должна быть создана конкретная документация по API.
В предыдущей статье шаг за шагом проходил процесс создания спецификаций API — этот шаг идет еще дальше, добавляя понятие тегов , определяющих , какие части документации генерировать или нет.
Python Docstrings
Давайте использовать один из тех же сервисов, что и раньше — вот его основная форма:
Джава
xxxxxxxxxx
1
# -*- coding: utf-8 -*-
2
3
# Zato
4
from zato.server.service import Int, Service
5
6
class RechargeCard(Service):
7
""" Recharges a pre-paid card.
8
Amount must not be less than 1 and it cannot be greater than 10000.
9
"""
10
11
class SimpleIO:
12
input_required = 'number', Int('amount')
13
output_required = Int('status')
Результат, когда генерируется как Sphinx, будет выглядеть так:
Теперь мы хотели бы добавить некоторые детали, к которым должны иметь доступ только внутренние пользователи — именно так следует изменять строку документации, предполагая на мгновение, что в компании есть две системы CRM, использование которых зависит от конкретного конечного пользователя. учетная запись…
Джава
xxxxxxxxxx
1
# -*- coding: utf-8 -*-
2
3
# Zato
4
from zato.server.service import Int, Service
5
6
class RechargeCard(Service):
7
""" Recharges a pre-paid card.
8
Amount must not be less than 1 and it cannot be greater than 10000.
9
10
#internal
11
12
For user accounts starting with QM - MyCRM is queried.
13
For any other account - MyCRM-2 is queried.
14
"""
15
16
class SimpleIO:
17
input_required = 'number', Int('amount')
18
output_required = Int('status')
… с соответствующим изменением в выводе:
Выше было то, что мы применили тег с именем #internal — все, что следует за ним, включается в вывод, только если этот тег запрашивается при создании документации.
Обратите внимание, что имя тега является произвольным, это может быть любое другое имя. Также обратите внимание, что в строке документации может быть больше, чем тег, например #confidential , #private или что-то еще.
Использование командной строки
Чтобы на самом деле включить тег #internal, команде zato apispec нужно сообщить об этом явно, как показано ниже:
Джава
xxxxxxxxxx
1
$ zato apispec /path/to/server \
2
--dir /path/to/output/directory \
3
--include api.* \
4
--tags public,internal
Если вы не дадите команде какие-либо теги, в итоговую документацию будет включена только открытая часть строки документации, одна без тегов.
Чтобы прояснить это для других разработчиков, вы также можете напрямую использовать тег public в команде — это облегчит понимание того, что вы хотите генерировать общедоступную информацию и ничего больше.
Джава
xxxxxxxxxx
1
$ zato apispec /path/to/server \
2
--dir /path/to/output/directory \
3
--include api.* \
4
--tags public
Завершение
Вот и все, вы сделали сейчас; вы можете хранить документацию по API в одном месте и включать только соответствующие части в зависимости от контекста. Это гарантирует, что независимо от того, кто является получателем вашей документации, она всегда будет генерироваться из одного источника, таким образом гарантируя, что весь вывод будет синхронизирован.