[NETCONF-1057] OpenApi: Eliminate TOP schemas Created: 14/Jun/23  Updated: 17/Aug/23  Resolved: 17/Aug/23

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

Type: Task Priority: Medium
Reporter: Ivan Hrasko Assignee: Ivan Hrasko
Resolution: Done Votes: 0
Labels: pt
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: File expected-TOP-removal-for-containers.json     File expected-TOP-removal-for-lists.json     File original.json    
Issue Links:
Blocks
blocks NETCONF-1077 OpenApi: Missing "data" path for POST... Open
is blocked by NETCONF-1054 OpenApi: POST examples are incorrect Resolved
is blocked by NETCONF-1059 OpenApi: Wrong XML GET example Resolved
Relates
relates to NETCONF-938 Cannot generate API docs for Junos de... In Review

 Description   

Currently, we generate for each container element (container, list) schema and, additionally, schema with _TOP prefix. _TOP prefix is used for PUT (JSON), PATCH (JSON) and GET operations.

Assuming that all operations are under path.

We can change our logic in the following way:

  1. For each container create its path.
  2. For each container create its schema - only one.
  3. Link container's path with schema for PUT (JSON), PATCH (JSON) and GET operations.
  4. Link container's parent path with schema for POST, PUT (XML) and PATCH (XML) operations.
  5. Continue.

 Comments   
Comment by Ivan Hrasko [ 16/Jun/23 ]

In NETCONF-1059 we can see that using _TOP schema for GET in XML is not correct.

Comment by Ivan Hrasko [ 01/Aug/23 ]

We cannot implement logic as proposed above because of the following reasons:

  1. ODL requires JSON payload be be enclosed by {} and element name as required by https://datatracker.ietf.org/doc/html/rfc8040#section-4.5. That is the reason why we have created TOP schemas.
  2. In fact, the schema created for container will never be show as required in #1 without creating additional schema which is level up.
  3. We cannot use parent's schema for this purpose because it contains data for other children as well.

But we can remove TOP schemas for lists and container and apply their logic directly in responses. This way we will get more cleaner and user friendly schemas listing at the bottom of generated OpenApi documentation.

 

Comment by Ivan Hrasko [ 01/Aug/23 ]

Please see proposed OpenApi docs after modifications: expected-TOP-removal-for-containers.json and expected-TOP-removal-for-lists.json. You can see the diffs against original.jsonto get idea what is going on.

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