Укажите свойство, которое никогда не следует отправлять в Swagger или OpenAPI

Question

Я бы хотел указать поля, которые никогда не следует отправлять из конечной точки. Например, скажем, я хочу убедиться, что ни одна конечная точка никогда не ответит user.passwordHash.

Есть ли что-то похожее на additionalProperties: false или required: true в OpenAPI?

Answer 1

OpenAPI 3.0 предоставляет ключевое слово writeOnly именно для этой цели:

Объявляет свойство как "только для записи". Следовательно, оно МОЖЕТ быть отправлено как часть запроса, но НЕ ДОЛЖНО отправляться как часть ответа .

Так что просто пометьте соответствующие свойства как writeOnly: true:

passwordHash:
  type: string
  writeOnly: true

Существует также readOnly для противоположного сценария - свойства, которые НЕ СЛЕДУЕТ отправлять в запросе, но МОГУТ отправляться в ответе. readOnly существует в OpenAPI 3.0 и 2.0.

Answer 2

Вы можете определить свойство как строку и установить максимальную длину равной нулю. Там нет ничего, что конкретно говорит additionalProperties: true, except for passwordHash.

type: object
properties:
    passwordHash:
        type: string
        format: password
        maxLength: 0

В качестве альтернативы вы можете просто пройти объект перед отправкой и удалить нежелательное свойство. Например:

function removeProperty(property, value) {
  if (Array.isArray(value)) {
    return value.map(item => removeProperty(property, item))

  } else if (value && typeof value === 'object') {
    const result = {}
    Object.keys(value)
      .forEach(key => {
        if (key !== property) {
          result[key] = removeProperty(property, value[key])
        }
      })
    return result

  } else {
    return value
  }
}

const object = {
  x: {
    y: {
      z: 1,
      secret: 'password'
    }
  }
}

const clean = removeProperty('secret', object)
console.log(clean) // => { x: { y: { z: 1 } } }