[Accesses API] Request bodies are not marked as required, and two of them are bare arrays #155

Problem description

None of the three POST operations in code/API_definitions/dedicated-network-accesses.yaml on main, which is also the content under review as 0.2.0-rc.1, marks its request body as required:

      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccessRequest'

In OpenAPI, required defaults to false, so a request with no body is valid against the specification for createAccess, addDevicesToAccess and removeDevicesFromAccess. None of them can be carried out that way: CreateAccessRequest requires networkId, and AddDevicesRequest and RemoveDevicesRequest have minItems: 1.

createNetwork in dedicated-network.yaml does set required: true.

Two of the three go further: the request body is the array of devices, rather than an object containing it.

    AddDevicesRequest:
      description: Request body used to add devices to an access
      allOf:
        - $ref: "#/components/schemas/Devices"
        - minItems: 1
        - maxItems: 100

RemoveDevicesRequest is the same. A body defined as a top-level array cannot gain a further field later without a breaking change.

createAccess in this same API carries its devices as a property of an object, as does DeviceAssignmentInput in qos-booking-and-assignment for the equivalent operation there. RetrieveSessionsInput in quality-on-demand and RetrieveAssignmentByDevice in qos-provisioning go further and show the combination asked for below: an object body whose device property is optional, declared required: true.

AddDevicesSuccess, the 201 response of addDevicesToAccess, is a top-level array with the same limitation, although required does not apply to a response.

Expected behavior

1. Define AddDevicesRequest and RemoveDevicesRequest as objects with a devices property holding the array, in line with CreateAccessRequest and with DeviceAssignmentInput in qos-booking-and-assignment.
2. With the bodies defined as objects, add required: true to the request bodies of createAccess, addDevicesToAccess and removeDevicesFromAccess.
3. Consider the same change for the AddDevicesSuccess response body.