[NETCONF-1054] OpenApi: POST examples are incorrect Created: 13/Jun/23  Updated: 12/Sep/23  Resolved: 08/Sep/23

Status: Resolved
Project: netconf
Component/s: restconf-openapi
Affects Version/s: None
Fix Version/s: 7.0.0, 4.0.9, 5.0.8, 6.0.2, 6.0.3

Type: Bug Priority: Highest
Reporter: Ivan Hrasko Assignee: Yaroslav Lastivka
Resolution: Done Votes: 0
Labels: pt
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: File expected-container-POST.json     File expected-container-in-container-POST.json     File expected-list-POST.json     File expected-list-in-list-POST.json     File netconf-1045.postman_collection-1.json     File original.json     File original2.json     File original3.json    
Issue Links:
Blocks
blocks NETCONF-1077 OpenApi: Missing "data" path for POST... Open
blocks NETCONF-1057 OpenApi: Eliminate TOP schemas Resolved
is blocked by NETCONF-1101 OpenApi: Remove incorrect list POST r... Resolved
is blocked by NETCONF-1071 OpenApi: Create POST request only for... Confirmed
Relates
relates to NETCONF-1137 OpenApi: Add description to POST requ... Resolved
relates to NETCONF-938 Cannot generate API docs for Junos de... In Review

 Description   

Issue A: Currently, ODL OpenApi generates examples for POST requests which contain all configuration children in payload.

This is not correct for both XML and JSON because we cannot create multiple resources with POST request.

Issue B: We can try to remove all data but the key from payload and we get working example for JSON:

POST /rests/data/network-topology:network-topology/topology=topology-id 
{
  "topology-id": "topology-id"
}

But even this approach does not work for XML, for example:

POST /rests/data/network-topology:network-topology/topology=topology-id  
<?xml version="1.0" encoding="UTF-8"?>
<topology xmlns="urn:TBD:params:xml:ns:yang:network-topology">
    <topology-id xmlns="urn:TBD:params:xml:ns:yang:network-topology">topology-id</topology-id>
</topology>

Because Swagger UI automatically encloses child into topology element (what's correct behavior for XML payloads).

Instead we should just POST one child as follows:

<?xml version="1.0" encoding="UTF-8"?>
<topology-id xmlns="urn:TBD:params:xml:ns:yang:network-topology">Some topology-id</topology-id>

Solution: POST payloads should contains only the key (lists with key) or empty body (lists without key or containers). Issue B will be addressed separately.

 Comments   
Comment by Ivan Hrasko [ 02/Aug/23 ]

It has been proven that we do not need to create cumbersome separate logic to create empty containers and lists but instead we can use schema for the first child of the container/list.

There are two cases:

  1. The first child is a container, see diff betweenoriginal2.json and expected-container-POST.json
  2. The first child is a list, see diff between original.json and expected-list-POST.json

IMO we have everything needed in BaseYangOpenApiGenerator#addPaths to easily implement all needed logic to distinguish between container and list and add child local name into schema name.

This approach solves the problem with XML payloads, too.

Comment by Ivan Hrasko [ 02/Aug/23 ]

The XML problem mentioned here is solved by NETCONF-1101.

Comment by Ivan Hrasko [ 24/Aug/23 ]

There are some problems on 5.0.x and 4.0.x branches. yaroslav.lastivka please explain/fix.

Comment by Yaroslav Lastivka [ 08/Sep/23 ]

Since we have applied changes https://git.opendaylight.org/gerrit/c/netconf/+/107479 on 5.0.x and 4.0.x, we faced the problem of unnecessary "_post", and "_xml" prefixes for POST requests.
Cherry-picking https://git.opendaylight.org/gerrit/c/netconf/+/107567#/q/cc6f8b0d874209c1888b3da2d4e5f448a068d3cc on 4.0.x and 5.0.x branches resolved this issue.

Comment by Ivan Hrasko [ 08/Sep/23 ]

OK, thanks.

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