Определение свойства со смешанным типом данных в Swagger
у меня уже есть рабочий документ swagger, который генерирует документацию с помощью проекта Swagger-UI, но у меня небольшая проблема.
Мангуст поддерживает тип данных Mixed
, который в основном является неструктурированным объектом, который может содержать что угодно. Однако, согласно спецификации Swagger, единственные возможные значения для свойства type
are string
, integer
, number
, boolean
и array
. Я не смог найти ничего в документации, на Google или в открытых выпусках для проекта Swagger-Spec на GitHub, который позволит использовать смешанные типы данных.
в документации Swagger-Spec, где они определяют type
параметры, они относятся к проекту JSON-схемы. Согласно спецификации JSON-Schema object
должен быть вариантом, но он не указан как потенциальное значение в спецификации Swagger.
кто-нибудь знает способ указать в документе Swagger, что свойство модели может содержать любые значение (либо одно примитивное значение, либо объект)?
примеры
определение схемы Мангуста:
var sampleSchema = new mongoose.Schema({
lookupCodes : { type: [mongoose.Schema.Types.Mixed] },
address: { type: mongoose.Schema.Types.Mixed }
});
mongoose.model('Sample', sampleSchema);
использование модели Мангуст:
var Sample = mongoose.model('Sample');
var doc = new Sample();
это все допустимые значения для двух определенных свойств:
doc.lookupCodes = ['A', 'B', 3, 4, 5, 'F'];
doc.lookupCodes = ['A', { code: '123' }, 5];
doc.address = '123 Main St., San Jose, CA, 95125';
doc.address = { street: '123 Main St.', city: 'San Jose', state: 'CA', postalCode: '95125'}
документ Swagger 1.2 (фрагмент):
"models": {
"Sample": {
"properties": {
"lookupCodes": {
"type": "array",
"items": {
"type": "??????"
},
"description": "An array of lookup codes. Codes can be strings, numbers or an object containing the `code` property."
},
"address": {
"type": "??????",
"description": "An address. This value can be a single string, containing all the elements of the address together, or it can be a structured object with each of the elements as separate properties of the object."
},
Я просто ищу способ, чтобы разработчик, просматривающий документацию, знал, что конкретное свойство в модель может принимать / возвращать любое значение (примитивную переменную или объект).
1 ответов
в вашем вопросе вы описываете два разных варианта использования.
первый-это использование массива со смешанными значениями, А второй-конкретное поле, которое может иметь любое значение (будь то объект, примитив и потенциально массив).
Swagger явно не поддерживает такое моделирование. Для этого есть несколько причин, но они концентрируются на детерминизме и языковой поддержке. В то время как динамические языки могут более легко поддерживать недетерминированные API и слабо типизированные языки могут легко поддерживать динамические типы, другие языки пострадают за это. API предназначены для взаимодействия, будучи независимыми от языка, поэтому вы должны учитывать эти ограничения.
в то время как Swagger подразумевается как инструмент документации, его экосистема инструментов включает решения, которые должны быть в состоянии производить и потреблять такие API практически на любом языке. Очевидно, что он не может иметь 100% покрытия, но он пытается избежать известных проблем.
Swagger 2.0 добавляет гораздо больше гибкости с точки зрения определения моделей, позволяя даже объекты свободной формы (и обратите внимание-объекты, а не примитивы). Хотя было бы крайне не рекомендуется использовать в целом, есть случаи использования, когда его просто нельзя избежать, но даже строго типизированные языки могут справиться с этим (я могу подробно остановиться на случаях использования, но это не относится к вопросу).
Как добавил информацию - подумайте об этом с точки зрения документации, и я буду использовать