В чем разница между enum и example в OpenAPI (Swagger)? - PullRequest
Новая
       33

В чем разница между enum и example в OpenAPI (Swagger)?

0 голосов
/ 13 марта 2020

В OpenAPI как пример , так и enum можно определить с помощью type: string, например: 

type: string
example:
      - FOOD
      - WATER

type: string
enum:
      - FOOD
      - WATER

Какая разница с точки зрения проверка с использованием любой из вышеуказанных структур? Можно ли использовать вышеуказанное взаимозаменяемо?

1 Ответ

0 голосов
/ 13 марта 2020

enum и example имеют разное значение и используются для разных целей.

enum указывает возможные значения для экземпляра (другими словами, это пределы возможных значений). Это аналог перечислений в C#, Java и других языках программирования. Например, enum: [FOOD, WATER] означает, что значение может быть либо "FOOD", либо "WATER", и ничего более.

example указывает пример значения для документации или других целей ( но не для проверки). Например, если у вас есть схема User со свойством username, вы можете указать demoUser в качестве примера имени пользователя. Но значение example не является возможным значением only для свойства, оно может иметь другие значения. 

User:
  type: object
  property:
    username:
      type: string
      example: demoUser

Схема может иметь как enum, так и example: 

type: string
enum:
  - FOOD
  - WATER
example: WATER

В отличие от enum, example не влияет на проверку. Однако такие инструменты, как генераторы кода и генераторы документации, могут ожидать, что значения example соответствуют их схемам. Такие инструменты пометят пример в вашем вопросе как недействительный, потому что схема определена как string, но значением примера является массив (т. Е. Другой тип данных). 

type: string
# Incorrect
example:
  - FOOD
  - WATER

# Correct
example: FOOD
...