Hi silverbullet2
Much depends how opinionated you would like to be in the design and what your needs are for extensibility. Here are some options that you may find helpful.
The most common mechanism would be to define a query parameter which accepts an array of strings and to use the description and examples to provide appropriate guidance for the API consumer.
An example of that would be:
parameters:
- in: query
name: fields
description: You can use the _fields_ parameter to restrict the set of properties returned to only those you explicitly specify. The properties are specified as a comma-separated list. For example, to return only the `name` and `color` properties of pets, you would set the parameter like `fields=name,color`
schema:
type: array
uniqueItems: true
items:
type: string
style: form
explode: false
examples:
singleProperty:
summary: Return only the name of the Pet
value: [name]
multipleProperties:
summary: Return the Pet's name, age and color
value: [name, age, color]
You can also define the parameter as an array of string enums. Enums are generally regarded as complete (e.g. you would not extend overtime in case of breaking a consumer implementation). However as this would only ever be for a request parameter and assuming you follow the practice of never removing a property from your design (e.g. breaking change), then it could fit your needs. This option gives you the ability to assert the condition against the specification itself.
parameters:
- in: query
name: fields
description: You can use the _fields_ parameter to restrict the set of properties returned to only those you explicitly specify. The properties are specified as a comma-separated list. For example, to return only the `name` and `color` properties of pets, you would set the parameter like `fields=name,color`
schema:
type: array
uniqueItems: true
items:
type: string
style: form
explode: false
examples:
singleProperty:
summary: Return only the name of the Pet
value: [name]
multipleProperties:
summary: Return the Pet's name, age and color
value: [name, age, color]
You could also specify an enum as part of an anyOf to guide the consumer but leave it open for further extension (not as strict as the previous option).
parameters:
- name: attributes
in: query
schema:
type: array
items:
type: string
anyOf:
- enum: [name, color, age]
- {}
required: false
description: You can use the _attributes_ parameter to restrict the set of properties returned to only those you explicitly specify. The properties are specified as a comma-separated list. For example, to return only the `name` and `color` properties of pets, you would set the parameter like `fields=name,color`. The known values are defined by the following enumeration [`name `, `age`, `color`] but this may extend overtime and other values provided will be processed if possible
style: form
explode: false
examples:
singleProperty:
summary: Return only the name of the Pet
value: [name]
multipleProperties:
summary: Return the Pet's name, age and color
value: [name, age, color]
Regardless of the chosen option, you would have to implement the logic to parse the query parameter and use the values to construct a response representation based on the provided selections.
I'd recommend providing some examples in your responses to demonstrate a full response representation as well as some filtered examples.
Example
responses:
'200':
description: Get Pets response
content:
application/json:
schema:
$ref: '#/components/schemas/Pets'
examples:
default:
value:
- name: spot
color: black
age: 2
eyeColor: brown
nameOnly - only name provided in query:
value:
- name: spot
nameAndAge - two propertiese provided in query:
value:
- name: spot
age: 2
I hope this helps you make a choice for your implementation.