Параметры адресной строки

Параметры ссылки: PathParameters

Декоратор @PathParameters() позволяет охарактеризовать параметр ссылки, который подразумевает некое динамическое значение. Чаще всего - идентификатор записи в базе данных, или какой-то вариант значения из ограниченного списка.

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

Декоратор принимает в качестве аргумента объект следующей структуры:

interface OpenApiPathParameter {  // ключ - полное значение параметра в адресной строке, включая ограничители регулярным выражением  [parameter: string]: {    name: string; // собственное имя параметра    description?: string; // описание параметра    in?: "query" | "header" | "cookie" | "path"; // местоположение аргумента: заголовок, путь, строка запроса, cookie, по умолчанию `path`    required?: Boolean; // признак обязательности, по умолчанию `true`    schema: SchemaObject; // схема данных параметра, удовлевторяющая критериям OAS  };}

Пример:

class Users {  @Bridge("/user_:user_id", User)  @PathParameters({    ":user_id": {      name: "user_id",      description: "Идентификатор пользователя",      schema: { type: "number" },    },  })  static userBridge(@Next() next) {    return next();  }}
class User {  @Get()  @Summary("Информация о пользователе")  static Info(@Params("user_id") userId) {    return models.Users.findById(userId);  }
  @Delete()  @Summary("Удалить пользователя")  static Info(@Params("user_id") userId) {    return models.Users.remove({ id: userId });  }}

Для всех методов в маршрутном узле User в документации в значении path будет заменено значение /user_:user_id на /user_{user_id}, и в список parameters добавлено описание:

{  "name": "user_id",  "description": "Идентификатор пользователя",  "schema": {    "type": "number"  },  "in": "path",  "required": true}

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

Поскольку спецификация OpenApi обязывает для описания параметра в пути использовать нотацию вида {param}, в то время как koa и другие веб-фреймворки используют для определения параметров нотацию :param, подразумевающую также возможное уточнение регулярным выражением, то в качестве значения parameter следует использовать именно полное написание параметра, включая символ : и возможные уточняющие правила.

Поэтому, если подразумевается сложное ограничение значение параметра, например, при работе со значениями типа ObjectId, характерными для базы MongoDb (то есть 24 символа, сочетающих латинские буквы и цифры), которое может быть написано как user_:user_id(.{24}), то в качестве ключа обязано быть именно это написание. Иначе парсер не сможет сделать замену, и в документации будет отсутствовать требуемое значение.

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

// используем класс User, чтобы сохранить в нем информацию о том// какими параметрами он будет подключаться в другие узлы@Use(User.Init)class User {  // имя параметра, по которому его можно получить в аргументах к методам  static id = "user_id";  // полное написание параметра с учетом ограничений регулярным выражением  static toString() {    return `:${this.id}(.{24})`;  }  // схема параметра, использующая оба точных значения имени и написания  static parameterSchema() {    return {      [`${this}`]: {        name: this.id,        description: "Идентификатор пользователя",        schema: {          type: "string",          pattern: "[a-z,0-9]{24}",        },      },    };  }
  @Middleware()  @PathParameters(User.parameterSchema())  static Init(@Params(User.id) userId, @Next() next, @Err() err) {    // ... логика инициации  }}
//... применение в других маршрутных узлах@Bridge(`/user_${User}`, User) // будет получено написание параметра включая ограничения по количеству символовclass Users {  // ... методы класса Users}

Параметры поисковой строки, заголовков и cookie: Parameters

Чтобы добавить в документацию информацию о параметрах, которые могут передаваться в поисковой строке (query_string), заголовках (headers) и cookie, необходимо использовать декоратор @Parameters.

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

interface OpenApiParameter {  name: string; // собственное имя параметра  in: "query" | "header" | "cookie" | "path"; // местоположение аргумента: заголовок, путь, строка запроса, cookie  schema: SchemaObject; // схема данных параметра, удовлевторяющая критериям OAS  description?: string; // описание параметра  required?: Boolean; // признак обязательности}

Пример:

class Brands {  @Summary("Справочник брендов")  @Responses({ status: 200, isArray: true, schema: models.Brands })  // доступны возможность использования поиска по полям  @Parameters(    // `title` (строка)    { name: "title", in: "query", schema: { type: "string" } },    // `enabled` (значение из списка)    { name: "enabled", in: "query", schema: { type: "string", enum: ["yes", "no"] } }  )  @Get()  static Index(@Query() query) {    return models.Brands.find({ ...query });  }}