Обработка параметров запроса в Swagger/OpenAPI: параметры пути, параметры запроса, тело запроса и параметры заголовка

Параметр запроса в контексте Swagger, также известный как спецификация OpenAPI (OAS), относится к параметру, который добавляется к URL-адресу конечной точки API для изменения поведения или предоставления дополнительной информации серверу. Эти параметры обычно используются для фильтрации, сортировки, разбиения на страницы или других целей манипулирования данными. Вот несколько распространенных методов обработки параметров запроса в Swagger/OpenAPI:

  1. Параметры пути. Эти параметры указываются в самом URL-пути и используются для идентификации конкретного ресурса. Параметры пути обозначаются фигурными скобками {}в URL-пути, а их значения могут быть указаны непосредственно в URL-адресе.

Пример:

GET /users/{userId}

В этом примере userId — это параметр пути, который определяет уникальный идентификатор для получения пользовательского ресурса.

  1. Параметры запроса. Эти параметры добавляются к URL-адресу после вопросительного знака ?и используются для изменения поведения запроса API. Параметры запроса состоят из пар ключ-значение и разделяются амперсандами &.

Пример:

GET /users?role=admin&status=active

В этом примере roleи status— это параметры запроса, которые фильтруют ответ, чтобы включить только пользователей с ролью «администратор» и статусом «активный».

  1. Тело запроса. Вместо использования параметров запроса конечные точки API могут принимать сложные структуры данных как часть тела запроса. Тело запроса может содержать различные форматы данных, такие как JSON или XML, что обеспечивает большую гибкость при передаче параметров.

Пример:

POST /users
{
  "name": "John Doe",
  "email": "johndoe@example.com",
  "role": "admin"
}

В этом примере конечная точка API ожидает, что объект JSON в теле запроса создаст нового пользователя.

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

Пример:

GET /users
Authorization: Bearer <access_token>

В этом примере токен доступа передается как параметр заголовка для аутентификации пользователя, делающего запрос.