Определение свойства со смешанным типом данных в 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 добавляет гораздо больше гибкости с точки зрения определения моделей, позволяя даже объекты свободной формы (и обратите внимание-объекты, а не примитивы). Хотя было бы крайне не рекомендуется использовать в целом, есть случаи использования, когда его просто нельзя избежать, но даже строго типизированные языки могут справиться с этим (я могу подробно остановиться на случаях использования, но это не относится к вопросу).

Как добавил информацию - подумайте об этом с точки зрения документации, и я буду использовать