search

open-education-api / specification

OpenAPI (fka Swagger) specification for the Open Education API.
Other
32 stars 26 forks source link

[Bug report]: #276

Closed jelmerderonde closed 12 months ago

jelmerderonde commented 2 years ago

Organization

SURF

Project

n/a

Contact Details

jelmer.deronde@surf.nl

Short description

Several requests in OOAPI (both in v4 and v5) support query parameters that have an array as the expected value. E.g. ?expand=person,offering. In this example an array of person and offering is passed to the expand query parameter.

In the documentation for such query parameters we state:

Optional properties to expand, separated by a comma

However, the OpenAPI specification supports multiple methods of parameter serialization, see: https://swagger.io/docs/specification/serialization/

The default serialization scheme for query parameters is form with explode. According to this default, the correct way to pass person and offering to the expand query parameter would be: ?expand=person&expand=offering. Which does not correspond to what we are suggesting in the documentation.

This has consequences for automatic tooling that relies upon the OOAPI specification, such as validation.

Version

v5

Usecase

Making sure tools such as validators work correctly.

Which institutions support this change?

No response

Proposed solution

Add the following two parameters to the relevant parameter specifications in the yaml files:

style: form
explode: false

Requests and responses

All requests that have query parameters that accept an array of values.

What is your question for the OOAPI work group?

No response

jelmerderonde commented 12 months ago

Closed by the merging of #280