Uploaded image for project: 'netconf'
  1. netconf
  2. NETCONF-1145

Remove identity from OpenAPI Schemas

    XMLWordPrintable

Details

    • Improvement
    • Status: Resolved
    • Medium
    • Resolution: Done
    • None
    • 7.0.0
    • restconf-openapi

    Description

      Currently, each identity in the Yang model is being transferred to an OpenAPI Schema object, which is unnecessary since they are only used as strings.
      For example:

      identity toast-type {
        description
            "Base for all bread types supported by the toaster.
             New bread types not listed here nay be added in the
             future.";
      }
      
      identity white-bread {
        base toast:toast-type;
        description "White bread.";
      } 

      is transferred to Schema object as:

      "toast-type": {
          "enum": [
             "toast-type",
             "wonder-bread",
             "frozen-bagel",
             "frozen-waffle",
             "white-bread",
             "wheat-bread",
             "hash-brown"
          ],
          "description": "Base for all bread types supported by the toaster.\nNew bread types not listed here nay be added in the\nfuture.",
          "title": "toast-type",
          "type": "string"
      },
      "white-bread": {
          "enum": [
             "white-bread"
          ],
          "description": "White bread.",
          "title": "white-bread",
          "type": "string"
      }

      Then, they are utilized as references for other objects.

      "toaster_make-toast_input": {
          "properties": {
             "toasterDoneness": {
                "description": "This variable controls how well-done is the\n      ensuing toast. It should be on a scale of 1 to 10.\n      Toast made at 10 generally is considered unfit\n      for human consumption; toast made at 1 is warmed\n      lightly.",
                "format": "int64",
                "default": 5,
                "example": 1,
                "type": "integer"
             },
             "toasterToastType": {
                "$ref": "#/components/schemas/toast-type"
             }
          }
      }

      To result in an example input that looks like this:

      {
        "input": {
          "toasterDoneness": 1,
          "toasterToastType": "toast-type"
        }
      } 

       

       

      A more effective solution would involve using only the string value instead of a reference.

      "toaster_make-toast_input": {
          "properties": {
             "toasterDoneness": {
                "description": "This variable controls how well-done is the\n      ensuing toast. It should be on a scale of 1 to 10.\n      Toast made at 10 generally is considered unfit\n      for human consumption; toast made at 1 is warmed\n      lightly.",
                "format": "int64",
                "default": 5,
                "example": 1,
                "type": "integer"
             },
             "toasterToastType": {
                "description": "This variable informs the toaster of the type of\n                   material that is being toasted. The toaster\n                   uses this information, combined with\n                   toasterDoneness, to compute for how\n                   long the material must be toasted to achieve\n                   the required doneness.",
                "default": "wheat-bread",
                "example": "toast-type",
                "type": "string"
             }
          }
      }

      This solution also addresses the issue of not using default values for identityref objects and addresses the problem of missing descriptions.

        leaf toasterToastType {
          type identityref {
            base toast:toast-type;
          }
          default 'wheat-bread';
          description
            "This variable informs the toaster of the type of
                   material that is being toasted. The toaster
                   uses this information, combined with
                   toasterDoneness, to compute for how
                   long the material must be toasted to achieve
                   the required doneness.";
        }
      } 

       

      IMHO, this method should be updated:
      DefinitionGenerator#processIdentityRefType
      and this should be removed

      DefinitionGenerator#processIdentities
       

      Attachments

        1. new_schema_enum.png
          62 kB
          Samuel Schneider
        2. new_schema.png
          54 kB
          Samuel Schneider
        3. old_schema.png
          52 kB
          Samuel Schneider
        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

        Activity

          People

            SamoSchneider Samuel Schneider
            PeterSuna Peter Suna
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved: