search

arc-archive / api-navigation

⛔️ DEPRECATED This component is being deprecated. Use `@api-components/amf-components` instead.
0 stars 1 forks source link

Order and placement of endpoints is invalid when AMF model presents incorrect endpoints order #5

Closed jarrodek closed 5 years ago

jarrodek commented 5 years ago

The following image presents the issue: image

API navigation makes assumption about the order of endpoints in generated AMF model. While processing paths it assumes that the next item in the array is either sub-resource or new path tree. It does not handle situation when RAML file specifies endpoints in a flat structure and without order.

This optimisation allows to reduce number of computations when generating UI model. To fix this the implementation would have to change to iterate over already parsed endpoints data which will increase complexity. This also would alter the order of endpoints in the UI compared to the one defined in the API file.

Other option would be to check if parent path(s) is not in the same tree and create a new tree. This would however generate duplicates in the tree. For example:

/processModel/{processModelUuid}
/tasks
/processModel/{processModelUuid}/start

instead of 

/processModel
  /{processModelUuid}
    /start
/tasks
twoplustwoone commented 5 years ago

What if api-navigation exposed an attribute called areEndpointsInOrder, which the component could use to determine whether or not to sort the endpoints?

If the endpoints in the AMF Model aren't ordered, I'm not sure there is a way to be able to order them according to the API Spec. So what if we just order them in alphabetical order according to path? That would at least put the endpoints correctly relative to their parents

~Or we could order them by their @id. If I'm not mistaken, this should lead to the endpoints being in the exact same order they were defined in the API spec~

EDIT: We can't order by id, because there is no guarantee that the ids will always return the correct order

jarrodek commented 5 years ago

The spec actually says that processors must respect order of endpoints. Because of that the console should render the following structure in the navigation menu:

/processModel/{processModelUuid}
/tasks
/processModel/{processModelUuid}/start

I am very uncomfortable altering anything that comes from API model. I can't know whether this is intentional or not. For any number of reasons it may be.

As for adding a property that enables sorting, it is possible to do. It would imagine it as adding a sort boolean property (and attribute) to enable soring of all groups (endpoints, types, security schemes, documentation). When this property is set it would call a sort function on endpoints list before processing the list to generate view model.

This option could be later on exposed on api-console element as sortNavigation property (sortnavigation attribute) but it wouldn't be enabled. Authors implementing the console can choose to do so. However in Anypoint platform this behavior wouldn't be supported.

jarrodek commented 5 years ago

This has been fixed by https://github.com/advanced-rest-client/api-navigation/pull/6