Как добавить несколько примеров в схему Swagger?

avatar
Traveling Tech Guy
1 июля 2021 в 16:32
861
0
0

Я использую Swagger с OAS3, так как мне нужна поддержка anyOf. У меня есть вызов API, который может принимать одну из двух возможных схем: account или address. Схема хорошо работает в Swagger: она показывает и проверяет. Но значение example показывает только первую схему. Я создал массив examples в соответствии с документацией, но понятия не имею, куда его добавить:

const accountSchema = {
  description: 'schema for adding a new account',
  type: 'object',
  properties: {
    account: {
      type: 'object',
      properties: {
        userId: {type: 'number'},
        platformId: {type: 'number'},
        name: {type: 'string'},
        key: {type: 'string'},
        secret: {type: 'string'},
        test: {type: 'boolean'},
      },
      required: ['userId', 'platformId', 'name', 'key', 'secret']
    }
  },
};

const ethereumAddressSchema = {
  description: 'schema for adding a new ethereum address',
  type: 'object',
  properties: {
    ethereum: {
      type: 'object',
      properties: {
        userId: {type: 'number'},
        name: {type: 'string'},
        address: {type: 'string'},
        chainId: {type: 'number'},
      },
      required: ['userId','name', 'address']
    }
  }
};

const examples = [
  {
    account: {
      "userId": 0,
      "platformId": 0,
      "name": "string",
      "key": "string",
      "secret": "string",
      "test": true
    },
  },
  {
    ethereum: {
      "userId": 0,
      "address": '0xfffffffffffffff',
      "name": "string",
      "chainId": 1,
    }
  }
];

const body = {
  anyOf: [accountSchema, ethereumAddressSchema]
};

const response = {
  type: 'object',
  properties: {
    accountId: {type: 'number'},
    reason: {type: 'string'}
  },
  required: []
};

const addAccountSchema = {
  description: 'Add a new account',
  tags: ['account'],
  produces: ['application/json'],
  summary: 'Add a new account',
  body,
  response: {
    200: {
      description: 'Account request valid',
      ...response
    },
    404: {
      description: 'Account request parameters not found',
      ...response
    },
    422: {
      description: 'Account request invalid',
      ...response
    }
  }
};

module.exports = addAccountSchema;

Куда добавить массив examples или есть лучший способ показать пользователю 2 возможные схемы в пользовательском интерфейсе?

Источник
Helen
1 июля 2021 в 21:54
0

1) Какую библиотеку вы используете для преобразования этого кода в файл OpenAPI? 2) Несколько примеров поддерживаются на уровне типа мультимедиа, т. е. в тексте запроса и определениях ответа — см. Добавление примеров. 3) Похоже, у вас смешанный синтаксис OAS3 (anyOf) и синтаксис OAS2 (produces). Убедитесь, что вы действительно используете OAS3.

Traveling Tech Guy
2 июля 2021 в 21:14
0

Спасибо @Helen: я использую fastify-swagger. Я просмотрел эту страницу, но все еще не был уверен, где в моем JSON помещаются примеры - пробовал разные вещи, и ничего не сработало. Не уверен насчет смешивания OAS2 и 3 - что я делал не так? Чем заменить produces?

Ответы (0)