Admin API Definitions Request Body Incorrectly Nested

[Aiden-Ziegelaar]

Description

The admin api has an incorrectly nested request body on the endpoint /admin/register/metadata.
On the endpoint Swagger JSON we see the following definitions:

"/admin/register/metadata": {
      "post": {
        "tags": ["Admin", "Register"],
        "summary": "Metadata Update",
        "description": "Indicate that a critical update to the metadata for Accredited Data Recipients has been made and should be obtained",
        "operationId": "metadataUpdate",
        "parameters": [
          {
            "in": "body",
            "name": "action",
            "required": true,
            "schema": {
              "$ref": "#/definitions/RequestMetaDataUpdate"
            }
          },
       ...]
    ...}

Expanding out the schemas gives us:

        "parameters": [
          {
            "in": "body",
            "name": "action",
            "required": true,
            "schema": {
                "type": "object",
                "required": ["data"],
                "properties": {
                  "data": {
                    "type": "object",
                    "required": ["action"],
                    "properties": {
                      "action": {
                        "type": "string",
                        "description": "The action to take for the meta data. At the moment the only option is REFRESH which requires the data holder to call the ACCC to refresh meta data as soon as practicable",
                        "default": "REFRESH",
                        "enum": ["REFRESH"]
                      }
                    }
                  },
                  "meta": {
                    "$ref": "#/definitions/Meta"
                  }
                }
            },
       ...]

This gives us a body parameter action that has a field data that contains a field action.
Thus the final body object type that looks like this:

{
  "action": {
    "data": {
      "action": "REFRESH"
    },
    "meta": {}
  }
}

Compared to the documented type:

{
  "data": {
    "action": "REFRESH"
  },
  "meta": {}
}

Area Affected

Admin API, specifically the post endpoint /admin/register/metadata

Change Proposed

I propose that the admin request bodies be documented the same way that the energy request bodies are documented, using the components/requestBodies area of the OpenAPI specification. This would also allow for type information application/json to be included in the definition.

[CDR-API-Stream]

This issue was discussed in the Maintenance Iteration 11 call. It was agreed to incorporate this change request into this maintenance iteration.

[CDR-API-Stream]

Hi @Aiden-Ziegelaar can you please confirm this is still an issue in release 1.17.0. The bug referenced no longer appears to be an issue in the latest Swagger.