Problems with Swagger APIView

[mikekistler]

Here are a few problems I discovered in the Swagger APIView when reviewing PR 19233. The APIView for this PR is here.

• The enum values for $expand are not shown
• Still wanting diff within tables - api-version was not removed and added.
• APIView does not handle inline schemas
• APIView does not handle allOf
• APIView does not handle additionalProperties with specific type (e.g. Map)

Details

Note: The PR has been updated since the APIView was created. I think the hash for the version that was used for APIView is 4bdad89.

• The enum values for $expand parameter are not shown.

  The parameter definition is:

  "ExpandSipConfiguration": {
      "name": "expand",
      "in": "query",
      "required": false,
      "type": "string",
      "description": "Sip configuration expand. Optional.",
      "x-ms-parameter-location": "method",
      "enum": [
        "trunks/health"
      ],
      "x-ms-enum": {
        "name": "ExpandEnum",
        "modelAsString": true,
        "values": [
          {
            "value": "trunks/health",
            "description": "Health state of a SIP trunk for routing calls."
          }
        ]
      }
    },
  

  but APIView only shows the parameter type:

  

• Still wanting diff within tables - api-version was not removed and added.

  

• APIView does not handle inline schemas

  The ExpandedTrunk schema defines the health property with an "inline" schema (not a $ref)

   "ExpandedTrunk": {
      "type": "object",
      "description": "Represents a SIP trunk for routing calls. See RFC 4904. Can be expanded with additional data.",
      "allOf": [
        {
          "$ref": "#/definitions/Trunk"
        }
      ],
      "properties": {
        "health": {
          "description": "Represents health state of a SIP trunk for routing calls.",
          "type": "object",
          "required": [
            "tls",
            "ping",
            "overall"
          ],
          "properties": {
            "tls": {
              "type": "object",
              "description": "The status of the TLS connections of the Trunk.",
              "required": [
                "status"
              ],
              "properties": {
                "status": {
                  "type": "string",
  ...
  

  but APIView shows it only as type: object

  

• APIView does not handle allOf

  For the same ExpandedTrunk schema of the previous item, the allOf: [ { "$ref": "#/definitions/Trunk" } ] is not rendered in the APIView

• APIView does not handle additionalProperties with specific type (e.g. Map)

  The domains and trunks properties of ExpandedSipConfiguration are declared "Maps" -- using additionalProperties -- of Domain and ExpandedTrunk respectively:

   "ExpandedSipConfiguration": {
      "description": "Represents a SIP configuration.\r\nWhen a call is being routed the routes are applied in the same order as in the routes list.\r\nA route is matched by its number pattern.\r\nCall is then directed into route's first available trunk, based on the order in the route's trunks list. The configuration can be expanded with additional data.",
      "type": "object",
      "properties": {
        "domains": {
          "description": "Validated Domains.\r\nMap key is domain.",
          "maxProperties": 250,
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/Domain"
          }
        },
        "trunks": {
          "description": "SIP trunks for routing calls.\r\nMap key is trunk's FQDN (1-249 characters).",
          "maxLength": 250,
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/ExpandedTrunk"
          }
        },
  

  but APIView renders these as simply type: object