[NETCONF-1145] Remove identity from OpenAPI Schemas Created: 30/Aug/23  Updated: 18/Oct/23  Resolved: 18/Oct/23

Status: Resolved
Project: netconf
Component/s: restconf-openapi
Affects Version/s: None
Fix Version/s: 7.0.0

Type: Improvement Priority: Medium
Reporter: Peter Suna Assignee: Samuel Schneider
Resolution: Done Votes: 0
Labels: pt
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: PNG File new_schema.png     PNG File new_schema_enum.png     PNG File old_schema.png    

 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
 



 Comments   
Comment by Samuel Schneider [ 18/Sep/23 ]

For reference this is how the schema toaster2_make-toast_input looks now:

and this is how it looks after proposed patch:

Generated at Wed Feb 07 20:16:47 UTC 2024 using Jira 8.20.10#820010-sha1:ace47f9899e9ee25d7157d59aa17ab06aee30d3d.