Содержание
При создании нового проекта ASP.NET Core Web API мы можем тестировать запросы к API различными способами, например, воспользоваться сторонними сервисами типа ReqBin, Postman и так далее. Вместе с тем, Visual Studio 2022 предоставляет достаточно удобный способ тестирования запросов API — использование http-файлов (файлов проекта с расширением .http).
Содержимое http-файла по умолчанию
Создадим новый проект ASP.NET Core Web API. По умолчанию Visual Studio создаст в проекте http-файл с названием, соответствующим имени проекта, например:
Откроем этот файл и посмотрим на его содержимое:
@HttpFiles_HostAddress = http://localhost:5292
GET {{HttpFiles_HostAddress}}/weatherforecast/
Accept: application/json
###
Первая строка в файле содержит переменную @HttpFiles_HostAddress, которой присвоено значение http://localhost:5292. Эта переменная далее используется для создания GET-запроса. Сам запрос, в данном случае, отправляется по адресу http://localhost:5292/weatherforecast/ и содержит заголовок Accept для согласования содержимого. Строка из трех символов «решетка» (###) используется для отделения одного запроса от другого.
Чтобы выполнить этот запрос мы должны воспользоваться одной из двух ссылок, расположенных над строкой запроса:
Ссылка «Отладка» запускает приложение в режиме отладки и выполнят запрос из http-файла. Ссылка «Отправить запрос» используется в момент, когда приложение уже запущено, то есть ссылки этого вида удобно использовать, когда нам необходимо, например, последовательно выполнить несколько запросов к API.
Кликнем по ссылке «Отладка» и посмотрим на результат выполнения запроса:
В редакторе откроется новое окно, содержащее всю необходимую информацию по запросу, которая размещается на нескольких вкладках:
Вкладка «Formatted» — содержит форматированный ответ сервера и заголовок Content-Type ответа (см. рисунок выше).
Вкладка «Raw» — содержит неформатированный ответ сервера
Вкладка «Headers» — содержит заголовки ответа сервера
Вкладка «Request» — содержит всю информацию по запросу
При выполнении запроса из http-файла по умолчанию также откроется окно браузера, содержащее ответ сервера. При использовании http-файла это лишняя операция, которая, к тому же, замедляет немного отладку приложения. Для того, чтобы этого не происходило, достаточно внести изменения в файл launchSettings.json, отключив автоматический запуск браузера, то есть указать для необходимого профиля запуска свойство "launchBrowser": false.
Выполнение различных HTTP-запросов к API
С использованием http-файлов мы можем выполнять самые различны HTTP-запросы — GET, POST, PUT, DELETE и т.д. Например, добавим в http-файл новый POST-запрос. Как только вы переместите курсор ниже строки ###, то откроется список выбора http-метода:
Выбираем запрос POST. Далее мы можем или воспользоваться уже определенной по умолчанию переменной для указания хоста, либо просто записать адрес хосту и путь запроса как строку. Для того, чтобы использовать в запросе значение переменной, необходимо напечатать двойные открывающие фигурные скобки. В результате редактор предложит список для выбора переменных:
Как можно видеть по рисунку, по умолчанию, редактор позволяет выбрать и уже встроенные переменные, такие как $projectUrl или переменные генерирующие какие-либо данные, например, переменная @randomInt будет генерировать произвольное целое число. Создадим URL запроса следующим образом:
POST {{HttpFiles_HostAddress}}/weatherforecast/
Следующий шаг — определение заголовков. Опять же, редактор предложит нам целый список наиболее распространенных заголовков, которые мы можем использовать:
Заголовки в http-файле размещаются строго под строкой запроса. Для POST-запроса мы должны определить заголовок Content-Type:
POST {{HttpFiles_HostAddress}}/weatherforecast/
Content-Type: application/json
Значение заголовков записывается без кавычек. При определении заголовков мы можем определять и собственные заголовки, например:
POST {{HttpFiles_HostAddress}}/weatherforecast/
Content-Type: application/json
X-Auth: 12345
Следующий шаг — необходимо определить тело запроса. Тело запроса записывается в http-файле через пустую строку после заголовков, например:
POST {{HttpFiles_HostAddress}}/weatherforecast/
Content-Type: application/json
X-Auth: 12345
{
"name": "Вася",
"surname": "Пупкин"
}
остается только добавить в конце запроса разделитель и запрос готов к использованию. В итоге мы получим запрос следующего содержания:
POST {{HttpFiles_HostAddress}}/weatherforecast/
Content-Type: application/json
X-Auth: 12345
{
"name": "Вася",
"surname": "Пупкин"
}
###
а весь http-файл будет выглядеть следующим образом:
@HttpFiles_HostAddress = http://localhost:5292
GET {{HttpFiles_HostAddress}}/weatherforecast/
Accept: application/json
###
POST {{HttpFiles_HostAddress}}/weatherforecast/
Content-Type: application/json
X-Auth: 12345
{
"name": "Вася",
"surname": "Пупкин"
}
###
Естественно, так как мы ничего не изменяли в проекте, кроме http-файла, то выполнение этого запроса приведет к ошибке, которую мы также увидим:
Аналогичным образом мы можем определять и другие запросы к API, соблюдая вышеперечисленные действия.
Переменные и комментарии в http-файлах
С переменными мы уже вкратце познакомились. Здесь только повторим, что все переменные начинаются с символа @ и каждая переменная располагается на новой строке. Например:
@Host = http://localhost
@Port = 5292
@Address = {{Host}}:{{Port}}
здесь мы определили три переменный, причем третьей переменной присвоили значения первых двух.
Что же касается комментариев в http-файлах, то, если нам необходимо разместить комментарий до начала определения запросов, то комментарий может начинаться с любых символов. Если же комментарий располагается внутри запроса, то он должен начинаться с последовательности символов #//. Например, мы можем указать такие комментарии внутри нашего файла:
@Host = http://localhost
@Port = 5292
@Address = {{Host}}:{{Port}}
#//Это комментарий в http-фале
это тоже комментарий в http-файле
GET {{Address}}/weatherforecast/
#это комментарий внутри запроса
Accept: application/json
#//это комментарий внутри запроса
###
POST {{Address}}/weatherforecast/
Content-Type: application/json
#//это комментарий внутри запроса
{
"name": "Вася",
"surname": "Пупкин"
}
###
Файлы среды
Файл среды — это обычный json-файл, который может размещаться рядом с http-файлом или в одном из родительских каталогов для http-файла и имеющий название http-client.env.json. При этом файл среды не должен находиться в папке проекта.
В файле среды можно указать имена одной или нескольких сред и под каждую среду определить свои значения переменных. Так как файл среды не должен находиться в папке проекта, то разместим и его и http-файл в новой папке, которую назовем ApiTest:
В файл http-client.env.json добавим следующий код:
{
"https": {
"Host": "https://localhost",
"Port": "7017"
},
"http": {
"Host": "http://localhost",
"Port": "5292"
}
}
Здесь https и http — имена сред (не путать с именами профилей запуска в файле launchSettings.json). Для каждой среды мы определили две переменные — Host и Port со своими значениями. Теперь изменим http-файл следующим образом:
@Address = {{Host}}:{{Port}}
GET {{Address}}/weatherforecast/
Accept: application/json
###
Значение переменных Host и Port будут определяться тем, какую среду мы выберем в http-файле. Имя среды выбирается в списке вверху справа:
Теперь нет необходимости переопределять значения переменных — достаточно определить из различные значения в файле среды и, в зависимости от потребностей, использовать те или иные значения.
Итого
В целом, можно сказать, что http-файлы — это достаточно удобный и, главное, встроенный в Visual Studio инструмент для тестирования запросов к API. При желании мы можем определить несколько http-файлов в проекте, определив в каждом свой набор запросов. Или, используя файл среды определять наборы переменных под различные ситуации. При этом, конечно, каждый волен выбирать каким инструментом тестирования пользоваться — http-файлами или какими-то своими, уже привычными сервисами.