What is the difference between enum and example in OpenAPI (Swagger)? - swagger-2.0

Question

In OpenAPI, both example and enum can be defined with type: string, such as:
type: string
example:
- FOOD
- WATER
type: string
enum:
- FOOD
- WATER
What difference does it make in terms of validation using any of the above structure? Can the above be used interchangeably?

Answer 1

enum and example have different meaning and are used for different purposes.
enum specifies possible values for an instance (in other words, it limits possible values). It's an analog of enums in C#, Java, and other programming languages. For example, enum: [FOOD, WATER] means that the value can be either "FOOD" or "WATER", and nothing else.
example specifies an example value for documentation or other purposes (but not for validation). Say, if you have the User schema with the username property, you can specify demoUser as an example username. But the example value is not the only possible value for the property, it can have other values.
User:
type: object
property:
username:
type: string
example: demoUser
A schema can have both enum and example:
type: string
enum:
- FOOD
- WATER
example: WATER
Unlike enum, example does not affect validation. However, tools like code generators and documentation generators may expect that the example values match their schemas. Such tools would flag the example in your question as invalid, because the schema is defined as string, but the example value is an array (i.e. a different data type).
type: string
# Incorrect
example:
- FOOD
- WATER
# Correct
example: FOOD