OpenAPI: Improve anydata example

Example template for anydata was
"<%s> ... </%s>", localName, localName
for both XML and JSON, which was incorrect.

Now we create empty object that is translatable to XML/JSON.
Into schema added description which informs the users that this is
unknown data and needs to be filled in by them.

JIRA: NETCONF-1319
Change-Id: I6440ff95f06ffa3d320ff50b93ee996ca1398052
Signed-off-by: lubos-cicut <lubos.cicut@pantheon.tech>

diff --git a/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/model/PropertyEntity.java b/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/model/PropertyEntity.java
index 84cf242491814b1adefed99da65225018bf14941..34baef96ef1cc9d1c76f40570c165c9fd4efb137 100644 (file)
--- a/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/model/PropertyEntity.java
+++ b/restconf/restconf-openapi/src/main/java/org/opendaylight/restconf/openapi/model/PropertyEntity.java
@@ -292,11 +292,12 @@ public class PropertyEntity {
         assert (leafNode instanceof AnydataSchemaNode || leafNode instanceof AnyxmlSchemaNode);
 
         final var leafDescription = leafNode.getDescription().orElse("");
-        generator.writeStringField(DESCRIPTION, leafDescription);
+        generator.writeStringField(DESCRIPTION,
+            leafDescription + " (This is unknown data, need to be filled by user.)");
 
-        final var localName = leafNode.getQName().getLocalName();
-        generator.writeStringField(EXAMPLE, String.format("<%s> ... </%s>", localName, localName));
-        generator.writeStringField(TYPE, STRING_TYPE);
+        generator.writeObjectFieldStart(EXAMPLE);
+        generator.writeEndObject();
+        generator.writeStringField(TYPE, OBJECT_TYPE);
         if (!leafNode.getQName().getNamespace().equals(parentNamespace)) {
             // If the parent is not from the same model, define the child XML namespace.
             buildXmlParameter(leafNode);

diff --git a/restconf/restconf-openapi/src/test/resources/yang-document/controller-all.json b/restconf/restconf-openapi/src/test/resources/yang-document/controller-all.json
index 647afab087aac4e6185e235295069b86eab1f7f2..fd5e55844c995ec73e605c3e2418d7f49d756397 100644 (file)
--- a/restconf/restconf-openapi/src/test/resources/yang-document/controller-all.json
+++ b/restconf/restconf-openapi/src/test/resources/yang-document/controller-all.json
@@ -12932,6 +12932,181 @@
         ],
         "parameters": []
       }
+    },
+    "/rests/data/typed-params:typed/anydata={key}": {
+      "put": {
+        "description": "",
+        "summary": "PUT - typed-params - Controller - anydata",
+        "requestBody": {
+          "description": "anydata",
+          "content": {
+            "application/json": {
+              "schema": {
+                "properties": {
+                  "typed-params:anydata": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/typed-params_typed_anydata",
+                      "type": "object"
+                    }
+                  }
+                }
+              }
+            },
+            "application/xml": {
+              "schema": {
+                "$ref": "#/components/schemas/typed-params_typed_anydata"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created"
+          },
+          "204": {
+            "description": "Updated"
+          }
+        },
+        "tags": [
+          "Controller typed-params"
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      },
+      "patch": {
+        "description": "",
+        "summary": "PATCH - typed-params - Controller - anydata",
+        "requestBody": {
+          "description": "anydata",
+          "content": {
+            "application/yang-data+json": {
+              "schema": {
+                "properties": {
+                  "typed-params:anydata": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/typed-params_typed_anydata",
+                      "type": "object"
+                    }
+                  }
+                }
+              }
+            },
+            "application/yang-data+xml": {
+              "schema": {
+                "$ref": "#/components/schemas/typed-params_typed_anydata"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "204": {
+            "description": "Updated"
+          }
+        },
+        "tags": [
+          "Controller typed-params"
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      },
+      "delete": {
+        "description": "",
+        "summary": "DELETE - Controller - typed-params - anydata",
+        "responses": {
+          "204": {
+            "description": "Deleted"
+          }
+        },
+        "tags": [
+          "Controller typed-params"
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      },
+      "get": {
+        "description": "",
+        "summary": "GET - Controller - typed-params - anydata",
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/xml": {
+                "schema": {
+                  "$ref": "#/components/schemas/typed-params_typed_anydata"
+                }
+              },
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "anydata": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/typed-params_typed_anydata",
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "tags": [
+          "Controller typed-params"
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "content",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "enum": [
+                "config",
+                "nonconfig",
+                "all"
+              ],
+              "type": "string"
+            }
+          }
+        ]
+      }
     }
   },
   "components": {
@@ -13203,6 +13378,13 @@
             "items": {
               "$ref": "#/components/schemas/typed-params_typed_uint32"
             }
+          },
+          "anydata": {
+            "description": "",
+            "items": {
+              "$ref": "#/components/schemas/typed-params_typed_anydata"
+            },
+            "type": "array"
           }
         },
         "xml": {
@@ -15010,6 +15192,26 @@
           "name": "output",
           "namespace": "urn:ietf:params:xml:ns:yang:test:action:types"
         }
+      },
+      "typed-params_typed_anydata": {
+        "properties": {
+          "key": {
+            "description": "",
+            "example": "Some key",
+            "type": "string"
+          },
+          "value": {
+            "description": "Anydata value. (This is unknown data, need to be filled by user.)",
+            "example": {},
+            "type": "object"
+          }
+        },
+        "title": "typed-params_typed_anydata",
+        "type": "object",
+        "xml": {
+          "name": "anydata",
+          "namespace": "urn:typed-params"
+        }
       }
     },
     "securitySchemes": {

diff --git a/restconf/restconf-openapi/src/test/resources/yang-document/controller-typed-params.json b/restconf/restconf-openapi/src/test/resources/yang-document/controller-typed-params.json
index b9e9a94e1f3990c9a08e248942c186107e108d61..0fa4d30a3b0397a2fe8d7ef6f55f56dd2bd88179 100644 (file)
--- a/restconf/restconf-openapi/src/test/resources/yang-document/controller-typed-params.json
+++ b/restconf/restconf-openapi/src/test/resources/yang-document/controller-typed-params.json
@@ -3187,6 +3187,181 @@
         "description": "",
         "summary": "PATCH - typed-params - Controller - enumeration"
       }
+    },
+    "/rests/data/typed-params:typed/anydata={key}": {
+      "put": {
+        "description": "",
+        "summary": "PUT - typed-params - Controller - anydata",
+        "requestBody": {
+          "description": "anydata",
+          "content": {
+            "application/json": {
+              "schema": {
+                "properties": {
+                  "typed-params:anydata": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/typed-params_typed_anydata",
+                      "type": "object"
+                    }
+                  }
+                }
+              }
+            },
+            "application/xml": {
+              "schema": {
+                "$ref": "#/components/schemas/typed-params_typed_anydata"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created"
+          },
+          "204": {
+            "description": "Updated"
+          }
+        },
+        "tags": [
+          "Controller typed-params"
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      },
+      "patch": {
+        "description": "",
+        "summary": "PATCH - typed-params - Controller - anydata",
+        "requestBody": {
+          "description": "anydata",
+          "content": {
+            "application/yang-data+json": {
+              "schema": {
+                "properties": {
+                  "typed-params:anydata": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/typed-params_typed_anydata",
+                      "type": "object"
+                    }
+                  }
+                }
+              }
+            },
+            "application/yang-data+xml": {
+              "schema": {
+                "$ref": "#/components/schemas/typed-params_typed_anydata"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "204": {
+            "description": "Updated"
+          }
+        },
+        "tags": [
+          "Controller typed-params"
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      },
+      "delete": {
+        "description": "",
+        "summary": "DELETE - Controller - typed-params - anydata",
+        "responses": {
+          "204": {
+            "description": "Deleted"
+          }
+        },
+        "tags": [
+          "Controller typed-params"
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      },
+      "get": {
+        "description": "",
+        "summary": "GET - Controller - typed-params - anydata",
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/xml": {
+                "schema": {
+                  "$ref": "#/components/schemas/typed-params_typed_anydata"
+                }
+              },
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "anydata": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/typed-params_typed_anydata",
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "tags": [
+          "Controller typed-params"
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "content",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "enum": [
+                "config",
+                "nonconfig",
+                "all"
+              ],
+              "type": "string"
+            }
+          }
+        ]
+      }
     }
   },
   "components": {
@@ -3417,6 +3592,13 @@
             "items": {
               "$ref": "#/components/schemas/typed-params_typed_int16"
             }
+          },
+          "anydata": {
+            "description": "",
+            "items": {
+              "$ref": "#/components/schemas/typed-params_typed_anydata"
+            },
+            "type": "array"
           }
         },
         "xml": {
@@ -3676,6 +3858,26 @@
         },
         "title": "typed-params_typed_string",
         "type": "object"
+      },
+      "typed-params_typed_anydata": {
+        "properties": {
+          "key": {
+            "description": "",
+            "example": "Some key",
+            "type": "string"
+          },
+          "value": {
+            "description": "Anydata value. (This is unknown data, need to be filled by user.)",
+            "example": {},
+            "type": "object"
+          }
+        },
+        "title": "typed-params_typed_anydata",
+        "type": "object",
+        "xml": {
+          "name": "anydata",
+          "namespace": "urn:typed-params"
+        }
       }
     },
     "securitySchemes": {

diff --git a/restconf/restconf-openapi/src/test/resources/yang-document/device-all.json b/restconf/restconf-openapi/src/test/resources/yang-document/device-all.json
index 18247a38cc9d9849824b2d21333b25bdd36c404d..091629188044bf864d421ff463d3db8cd5bcfd26 100644 (file)
--- a/restconf/restconf-openapi/src/test/resources/yang-document/device-all.json
+++ b/restconf/restconf-openapi/src/test/resources/yang-document/device-all.json
@@ -12960,6 +12960,181 @@
         ],
         "parameters": []
       }
+    },
+    "/rests/data/nodes/node=123/yang-ext:mount/typed-params:typed/anydata={key}": {
+      "delete": {
+        "description": "",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Deleted"
+          }
+        },
+        "summary": "DELETE - 123 - typed-params - anydata",
+        "tags": [
+          "123 typed-params"
+        ]
+      },
+      "get": {
+        "description": "",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "content",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "enum": [
+                "config",
+                "nonconfig",
+                "all"
+              ],
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "anydata": {
+                      "items": {
+                        "$ref": "#/components/schemas/typed-params_typed_anydata",
+                        "type": "object"
+                      },
+                      "type": "array"
+                    }
+                  }
+                }
+              },
+              "application/xml": {
+                "schema": {
+                  "$ref": "#/components/schemas/typed-params_typed_anydata"
+                }
+              }
+            },
+            "description": "200"
+          }
+        },
+        "summary": "GET - 123 - typed-params - anydata",
+        "tags": [
+          "123 typed-params"
+        ]
+      },
+      "patch": {
+        "description": "",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/yang-data+json": {
+              "schema": {
+                "properties": {
+                  "typed-params:anydata": {
+                    "items": {
+                      "$ref": "#/components/schemas/typed-params_typed_anydata",
+                      "type": "object"
+                    },
+                    "type": "array"
+                  }
+                }
+              }
+            },
+            "application/yang-data+xml": {
+              "schema": {
+                "$ref": "#/components/schemas/typed-params_typed_anydata"
+              }
+            }
+          },
+          "description": "anydata"
+        },
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "204": {
+            "description": "Updated"
+          }
+        },
+        "summary": "PATCH - typed-params - 123 - anydata",
+        "tags": [
+          "123 typed-params"
+        ]
+      },
+      "put": {
+        "description": "",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "properties": {
+                  "typed-params:anydata": {
+                    "items": {
+                      "$ref": "#/components/schemas/typed-params_typed_anydata",
+                      "type": "object"
+                    },
+                    "type": "array"
+                  }
+                }
+              }
+            },
+            "application/xml": {
+              "schema": {
+                "$ref": "#/components/schemas/typed-params_typed_anydata"
+              }
+            }
+          },
+          "description": "anydata"
+        },
+        "responses": {
+          "201": {
+            "description": "Created"
+          },
+          "204": {
+            "description": "Updated"
+          }
+        },
+        "summary": "PUT - typed-params - 123 - anydata",
+        "tags": [
+          "123 typed-params"
+        ]
+      }
     }
   },
   "components": {
@@ -13231,6 +13406,13 @@
             "items": {
               "$ref": "#/components/schemas/typed-params_typed_bits"
             }
+          },
+          "anydata": {
+            "description": "",
+            "items": {
+              "$ref": "#/components/schemas/typed-params_typed_anydata"
+            },
+            "type": "array"
           }
         },
         "xml": {
@@ -15038,6 +15220,26 @@
           "name": "output",
           "namespace": "urn:ietf:params:xml:ns:yang:test:action:types"
         }
+      },
+      "typed-params_typed_anydata": {
+        "properties": {
+          "key": {
+            "description": "",
+            "example": "Some key",
+            "type": "string"
+          },
+          "value": {
+            "description": "Anydata value. (This is unknown data, need to be filled by user.)",
+            "example": {},
+            "type": "object"
+          }
+        },
+        "title": "typed-params_typed_anydata",
+        "type": "object",
+        "xml": {
+          "name": "anydata",
+          "namespace": "urn:typed-params"
+        }
       }
     },
     "securitySchemes": {

diff --git a/restconf/restconf-openapi/src/test/resources/yang-document/device-typed-params.json b/restconf/restconf-openapi/src/test/resources/yang-document/device-typed-params.json
index a936d5b213e5fee3eae79f612fb37cbfc99ebfa1..4567ec6a420d686482c85443a1a0e0344eafdbb6 100644 (file)
--- a/restconf/restconf-openapi/src/test/resources/yang-document/device-typed-params.json
+++ b/restconf/restconf-openapi/src/test/resources/yang-document/device-typed-params.json
@@ -3187,6 +3187,181 @@
         "description": "\n\nNote:\nIn example payload, you can see only the first data node child of the resource to be created, following the\nguidelines of RFC 8040, which allows us to create only one resource in POST request.\n",
         "summary": "POST - 123 - typed-params - typed-params"
       }
+    },
+    "/rests/data/nodes/node=123/yang-ext:mount/typed-params:typed/anydata={key}": {
+      "delete": {
+        "description": "",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Deleted"
+          }
+        },
+        "summary": "DELETE - 123 - typed-params - anydata",
+        "tags": [
+          "123 typed-params"
+        ]
+      },
+      "get": {
+        "description": "",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "content",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "enum": [
+                "config",
+                "nonconfig",
+                "all"
+              ],
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "anydata": {
+                      "items": {
+                        "$ref": "#/components/schemas/typed-params_typed_anydata",
+                        "type": "object"
+                      },
+                      "type": "array"
+                    }
+                  }
+                }
+              },
+              "application/xml": {
+                "schema": {
+                  "$ref": "#/components/schemas/typed-params_typed_anydata"
+                }
+              }
+            },
+            "description": "200"
+          }
+        },
+        "summary": "GET - 123 - typed-params - anydata",
+        "tags": [
+          "123 typed-params"
+        ]
+      },
+      "patch": {
+        "description": "",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/yang-data+json": {
+              "schema": {
+                "properties": {
+                  "typed-params:anydata": {
+                    "items": {
+                      "$ref": "#/components/schemas/typed-params_typed_anydata",
+                      "type": "object"
+                    },
+                    "type": "array"
+                  }
+                }
+              }
+            },
+            "application/yang-data+xml": {
+              "schema": {
+                "$ref": "#/components/schemas/typed-params_typed_anydata"
+              }
+            }
+          },
+          "description": "anydata"
+        },
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "204": {
+            "description": "Updated"
+          }
+        },
+        "summary": "PATCH - typed-params - 123 - anydata",
+        "tags": [
+          "123 typed-params"
+        ]
+      },
+      "put": {
+        "description": "",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "properties": {
+                  "typed-params:anydata": {
+                    "items": {
+                      "$ref": "#/components/schemas/typed-params_typed_anydata",
+                      "type": "object"
+                    },
+                    "type": "array"
+                  }
+                }
+              }
+            },
+            "application/xml": {
+              "schema": {
+                "$ref": "#/components/schemas/typed-params_typed_anydata"
+              }
+            }
+          },
+          "description": "anydata"
+        },
+        "responses": {
+          "201": {
+            "description": "Created"
+          },
+          "204": {
+            "description": "Updated"
+          }
+        },
+        "summary": "PUT - typed-params - 123 - anydata",
+        "tags": [
+          "123 typed-params"
+        ]
+      }
     }
   },
   "components": {
@@ -3417,6 +3592,13 @@
             "items": {
               "$ref": "#/components/schemas/typed-params_typed_int16"
             }
+          },
+          "anydata": {
+            "description": "",
+            "items": {
+              "$ref": "#/components/schemas/typed-params_typed_anydata"
+            },
+            "type": "array"
           }
         },
         "xml": {
@@ -3676,6 +3858,26 @@
         },
         "title": "typed-params_typed_string",
         "type": "object"
+      },
+      "typed-params_typed_anydata": {
+        "properties": {
+          "key": {
+            "description": "",
+            "example": "Some key",
+            "type": "string"
+          },
+          "value": {
+            "description": "Anydata value. (This is unknown data, need to be filled by user.)",
+            "example": {},
+            "type": "object"
+          }
+        },
+        "title": "typed-params_typed_anydata",
+        "type": "object",
+        "xml": {
+          "name": "anydata",
+          "namespace": "urn:typed-params"
+        }
       }
     },
     "securitySchemes": {

diff --git a/restconf/restconf-openapi/src/test/resources/yang/typed-params.yang b/restconf/restconf-openapi/src/test/resources/yang/typed-params.yang
index 67bc93cd78eeae1b864c5e3e644f4db829506277..b5dbc3b3a70468012b676da4489c4783db2fef13 100644 (file)
--- a/restconf/restconf-openapi/src/test/resources/yang/typed-params.yang
+++ b/restconf/restconf-openapi/src/test/resources/yang/typed-params.yang
@@ -172,5 +172,14 @@ module typed-params {
                 type string;
             }
         }
+        list anydata {
+            key key;
+            leaf key {
+                type string;
+            }
+            anydata value {
+                description "Anydata value.";
+            }
+        }
     }
 }
\ No newline at end of file