ApiLeaf может быть самым простым инструментом для создания документов в истории

задняя часть внешний интерфейс API контрольная работа

Введение

Я считаю, что многие студенты, которые пишут back-end интерфейсы, такие же, как и я, у них очень много головной боли при подготовке интерфейсных документов: написание документов занимает много времени и труда, что реально ударяет по энтузиазму разработчиков к разработке, особенно в гибкой разработке малых и средних проектов, часто написании документов Это занимает больше времени, чем разработка интерфейса.

Для крупных проектов и зрелых команд обычно существуют зрелые инструменты автоматизации тестирования интерфейса, которые объединяют тестирование интерфейса, автоматическое построение и фиктивные данные, но небольшие и средние группы разработчиков (например, студенческие организации) часто не имеют возможности создавать аналогичные платформы. .

Поэтому многие люди просто не ведут документы, а это увеличит затраты на связь между фронтом и бэкендом и снизит эффективность работы всей команды.

Поскольку так называемая «лень — это первая движущая сила человеческого прогресса», чтобы свести к минимуму лень при написании документов, я попытался разработать этот инструмент для создания документов и платформу управления:ApiLeaf, если вы также являетесь бэкэнд-разработчиком в небольшой команде и, как и я, не любите писать документацию, давайте посмотрим, может ли это вам помочь!

основная идея

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

Например, теперь у нас есть интерфейс, который вычисляет A + B, а URL-адрес запросаhttp://localhost:8080/add, нам нужно сделать тест на нем, поэтому мы POST следующие данные:

{
	"a": 1,
	"b": 2
}

Затем успешно получен ответ от сервера:

{
	"code": 0,
	"result": 3
}

Тест интерфейса завершен, посмотрим, какие данные можно получить от этого процесса:

  • запрошенный URL-адрес
  • Запрашиваемый метод Метод
  • Заголовки запроса
  • Структура тела запроса
  • Пример правильного запроса

а также

  • Заголовки ответа
  • Структура тела ответа
  • Пример правильного ответа

По этому содержимому достаточно сгенерировать документацию соответствующего интерфейса.Обычно достаточно добавить несколько базовых описаний к полям в Заголовки и Тело, чтобы сгенерировать достаточно подробную документацию.

ApiLeaf основан на этой идее. Пока вы тестируете интерфейс на ApiLeaf, он может записывать данные запроса и ответа в процессе тестирования и автоматически создавать инфраструктуру документа. В большинстве случаев вам нужно только добавить некоторые базовые описания (если вы используете функцию словаря данных, описанную ниже, вам даже не нужно заполнять описание), вы можете быстро создать документацию.

Демонстрация автоматической генерации документов

Много глупостей сказано, почему бы вам не попробовать? Первый визитApiLeaf, зарегистрируйтесь и войдите в свою учетную запись, затем нажмите главную панель на главной странице, чтобы войти в личный кабинет.

Личная панель предоставляет интерфейс управления документами.Прежде чем мы начнем пытаться автоматически генерировать документы, нам нужно создать проект.

существуетпроект я создалпанель, нажмитеНовый проектЧтобы создать проект, вам просто нужно заполнить название проекта и описание:

Далее нажмите раскрывающееся меню в правом верхнем углу и выберитеНачать тестВы можете войти в тестовую панель HTTP, и вы увидите интерфейс, похожий на POSTMAN.

Теперь давайте протестируем интерфейс.В качестве примера возьмем мой локальный тестовый интерфейс входа в систему.Этот интерфейс получаетlogin_nameиpassword, после того, как успех возвращает базовую модель вошедшего в систему пользователя, мы добавляем запрошенный URL и тело, а затем можем отправить запрос для тестирования HTTP:

Использование листьев APIfetchЧтобы отправить этот запрос, вы можете использовать его для тестирования локального интерфейса и моделирования реальной среды внешнего запроса в наибольшей степени, но вам нужно уделить немного внимания междоменным проблемам.

Если тест прошел успешно, вы можете увидеть содержимое ответа, возвращенного сервером, на панели «Ответ» ниже:

Если тест не пройден и ответ не может быть получен, вы можете открыть консоль браузера, чтобы отследить ненормальную причину запроса на выборку.

Теперь мы можем нажать «Создать документ», чтобы перейти на страницу редактирования интерфейса документа.

В первую очередь нам необходимо дополнить основную информацию интерфейса, выбрать проект, к которому принадлежит интерфейс (документ этого интерфейса будет автоматически включен в общий документ проекта после генерации), URL и МЕТОД были автоматически заполняется и добавляется имя и описание. Вы также можете указать имя группы для интерфейса, которое используется для классификации и управления интерфейсом во всем проекте, что очень полезно, когда в проекте много интерфейсов.

Далее мы увидим множество редакторов JSON.ApiLeaf разделит данные, полученные из предыдущего теста, на следующие 7 частей, и автоматически заполнит редакторы соответствующих частей:

  • Заголовки запроса API (Заголовки)
  • Параметры запроса API (QueryString)
  • Тело запроса API (Body)
  • Пример запроса API
  • Заголовки ответа API (Заголовки)
  • Тело ответа API (Body)
  • Пример ответа API

Взяв тест только что в качестве примера, поле редактирования тела ответа будет заполнено следующим содержимым

[
	{
		"body_key": "code",
		"body_type": "integer",
		"body_description": ""
	},
	{
		"body_key": "user",
		"body_type": "object",
		"body_description": ""
	},
	{
		"body_key": "user.id",
		"body_type": "integer",
		"body_description": ""
	},
	{
		"body_key": "user.name",
		"body_type": "string",
		"body_description": ""
	},
	{
		"body_key": "user.sex",
		"body_type": "string",
		"body_description": ""
	},
	{
		"body_key": "user.age",
		"body_type": "integer",
		"body_description": ""
	}
]

ApiLeaf извлечет все ключи из ответа JSON, чтобы построить иерархическую связь (с.split) и автоматически выводить их типы данных, все, что вам нужно сделать, это проверитьbody_typeисправить и добавитьbody_descriptionОписаний полей достаточно.

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

Следует отметить, что содержимое в поле редактирования должно быть допустимым JSON, и существуют требования к ключу каждого поля, поэтому, пожалуйста, не изменяйте структуру содержащегося объекта случайно, иначе это может привести к ошибкам (почему JSON метод Fill, конечно же, потому что так можно полениться и не надо делать интерфейс. . )

После ответа на эти простые вопросы, требующие заполнения, можно создать документ, и вы увидите интерфейс предварительного просмотра этого документа API:

Обеспечьте вкладки запроса и ответа для отображения соответствующих инструкций соответственно.

На этом генерация документа структуры завершена, в идеале процесс тестирования + генерация документа не превышает 1 минуты, что очень удобно.

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

Словарь данных и автоматическое сопоставление

Словарь данных относится к базовой структуре данных, которая часто используется в проекте, например, в тестовом проекте.UserОбъект, как основное определение пользовательских данных, может использоваться во многих интерфейсах.Если вы используете Api Leaf для автоматического создания документов, вам может потребоваться заполнить несколько раз.UserОписание каждого поля, которое мы не можем принять.

Идея Api Leaf состоит в том, чтобы создать общую структуру данных в словарь данных и сохранить ее в проекте.С одной стороны, фронтенд-персоналу удобно быстро получить общие определения структуры данных, а с другой С другой стороны, когда структура данных повторяется, она может автоматически сопоставляться со связанными структурами данных словаря, что сокращает повторяющийся процесс написания инструкций.

Сказав так много, давайте рассмотрим пример, чтобы увидеть, как используется словарь данных:

Создать словарь данных

Перейти на страницу просмотра документов указанного проекта, нажать на верхнюю панель навигацииСловарь данныхдля входа на страницу списка словаря данных, а затем щелкнитеДобавить новый словарькнопка для входа на страницу редактирования словаря данных:

После заполнения имени типа и описания словаря данных на странице редактирования (обратите внимание, что в проекте не может быть двух словарей данных с одинаковым именем типа), вы можете дополнить определения полей и описания словаря данных, добавив их вручную Словарь данных анализируется из JSON.

В качестве примера давайте создадим этот словарь данных, используя объект User JSON, возвращенный в ответе только что:

После нажатия Parse все имена и типы полей могут быть добавлены автоматически, вам нужно вручную проверить правильность этих типов и добавить соответствующие инструкции:

последний кликDoneкнопку для создания полного словаря данных.

Автоматч

Теперь, когда у нас есть словарь данных, давайте посмотрим, как использовать функцию автоматической обработки.

Предположим теперь, что в проекте есть еще один интерфейс/user/{id}/profile, через этот интерфейс может быть получена личная информация указанного пользователя (то есть его User model), после чего мы проводим тест и получаем следующий ответ:

{
	"code": 0,
	"user": {
		"id": 17,
		"name": "lumin",
		"sex": "male",
		"age": 20
	}
}

Теперь нам нужно сгенерировать документ. В это время вы обнаружите, что этот тип пользователя был определен один раз в предыдущем интерфейсе входа. Можно ли снова переписать описание каждого поля?

Ответ, конечно, НЕТ, если вы определили эту структуру данных в словаре данных, вам не нужно заполнять какие-либоbody_descriptionполе, нажмите «Создать документ напрямую», а затем войдите на страницу просмотра документа проекта, вы найдете еще несколько кнопок в поле описания ответа...

Затем нажмите эту кнопку, и произойдет волшебство: Api Leaf автоматически сопоставит наиболее вероятное определение данных в словаре данных проекта в соответствии со всеми ключами выбранного поля, В этом примере мы получим степень совпадения 100% Определение пользовательских данных, да, это то, что нам нужно!

Функция сопоставления попытается найти наиболее похожую структуру в словаре данных, но будут случаи, когда поиск не может быть найден или скорость совпадения очень низкая, например:

Совпадающие поля будут выделены жирным шрифтом.

Когда коэффициент совпадения ниже 60%, очень вероятно, что это не то определение данных, которое вам нужно.В это время честно дополните словарь данных или определение поля~

Пока определен часто используемый словарь данных, это сэкономит много усилий при создании документов, поэтому после создания основных определений данных проекта (таких как структура таблицы базы данных) добавьте их в словарь данных!

Уведомление

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

полная структура документа

Был представлен базовый процесс использования Api Leaf для создания документа проекта.Давайте посмотрим на информацию, которую полный документ проекта может предоставить с точки зрения разработчиков интерфейса/клиентов.

Ты сможешькликните сюдаОзнакомьтесь с простым демонстрационным документом, предоставленным официальным лицом.

Полный проектный документ в Api Leaf включает следующие 3 части:

  1. Документация интерфейса API: генерируется и агрегируется с помощью HTTP-тестов.
  2. Список кодов состояния: различные коды состояния, используемые в проекте.
  3. Словарь данных: часто используемые определения структуры данных

Вы можете быстро переключаться между тремя частями с помощью панели навигации вверху, и каждая часть имеет панель навигации слева для быстрого определения местоположения связанных определений:

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

разное

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

Это первый инструмент с открытым исходным кодом, который я сделал.Он больше спроектирован и разработан с точки зрения моей собственной команды, но я считаю, что большинство малых и средних групп гибкой разработки, таких как наша команда, особенно студенческие команды, такой инструмент необходимо для облегчения общения и обмена между членами.

Поскольку он разрабатывается отдельными людьми, есть области, которые необходимо отполировать с точки зрения красоты страницы и логики использования. Я продолжу обновлять и оптимизировать соответствующие функции в будущем.

Разработчики могут попробовать его и оставить ценные комментарии!

  • Автор: Лю Мин@No Dishwashing Studio
  • гитхаб: https://github.com/MarkLux/ApiLeaf

Кстати, я зарыл на странице несколько пасхалок, кому интересно, могут поискать~

Категории