The path order in the yml API is not ordered and does not match the path in the UI

[Nicnl]

Hello,

I don't know if this is a bug or en enhancement, but here it is

Description of the issue

Let's say I want to create an API with four paths:

• POST /bar
• GET /bar/{id_bar}
• POST /foo
• GET /foo/{id_foo}

But let's consider I insert them using the UI in this specific order:

• GET /foo/{id_foo}
• POST /bar
• GET /bar/{id_bar}
• POST /foo

The UI is nice and the paths appear sorted, matching what I want:

But, the resulting yml is not ordered and doesn't match what appears in the UI:

openapi: 3.0.2
info:
    title: 'Test API'
    version: 1.0.0
paths:
    '/foo/{id_foo}': {}
    /bar: {}
    '/bar/{id_bar}': {}
    /foo: {}

Normally, I would not really care about the order of the paths in the raw yml file
But the thing is that ReDoc follows the order of the paths in the yml

So the resulting documentation is not ordered:

This is a problem because once an API starts living, some paths are updated, some are deleted and some are created
This means that the resulting documentation is quickly becoming a garbled mess

What can be done

I have a few ideas, they're far from perfect but it's a start
Maybe we can build on them and elaborate

• Always sort the outputted API
  Pros: Easy to implement (I think?)
  Cons: Users are unable to chose their own ordering
• Add an option to sort the paths in the outputted API
  Pros: Easy to implement (I think?)
  Cons: The user is not able to change the order of individual paths
• Modify the UI so that the displayed paths are not ordered,
  and add a button to sort everything + buttons to move individual paths up and down Pros: Would solve everything
  Cons: Hardest to implement (I think?)

[Nicnl]

Oops, sorry, I forgot to attach the YML I used for the ReDoc screenshots
(The one I pasted doesn't have operations, so ReDoc generates an empty doc)

openapi: 3.0.2
info:
    title: 'Test API'
    version: 1.0.0
paths:
    '/foo/{id_foo}':
        get:
            summary: 'Obtain a foo'
            parameters:
                -
                    name: id_foo
                    in: path
                    required: true
                    schema:
                        type: number
            responses:
                '201':
                    description: 'A foo'
    /bar:
        post:
            summary: 'Create a bar'
            responses:
                '200':
                    description: 'A bar'
    '/bar/{id_bar}':
        get:
            summary: 'Obtain a bar'
            parameters:
                -
                    name: id_bar
                    in: path
                    required: true
                    schema:
                        type: number
            responses:
                '201':
                    description: 'Bar created'
    /foo:
        post:
            summary: 'Create a foo'
            responses:
                '200':
                    description: 'Foo created'

[EricWittmann]

This is an interesting issue that surprisingly has not come up before! There are actually a few places in the UI where I think we should be providing your option C - display the items in the order they appear in the document but offer options to sort and re-order (drag and drop, presumably).

That said, a temporary solution would be to sort the paths and other lists before handing the content to ReDoc. That would be fast and easy to do and would fix the specific problem of the Apicurio "Preview" feature.

Any thoughts/ideas on this, @jsenko ?

[kesuskim]

I ran into this issues as well; my observation on this is that APICURIO just appends new definition to current YAML in either when we create new paths; or when we totally replace yaml (for example for individual path if I modify something from 'source' tab).

I manually manipulate database to fix this after I modify YAML myself (then update the column), and somehow everything broken up that I have to remove project and restart again.

As @EricWittmann said I think it is best to sort the paths and other lists before handing the content to ReDoc, or we could use another button in 'source' tab next to 'Format' button (maybe naming as 'Sort Paths'), that we can handle by ourselves.

[BenjaminPelletier]

Like #394, I think the general idea here is that the Apicurio UI should correspond with the YAML ordering for all types of elements (paths, fields, probably data types) because that order is sometimes important (like for generating documentation).

One simple thing that would be helpful here is to enable the Save button when editing the raw YAML and changing just the order of elements. Currently, Apicurio is a bit too smart and grays out the Save button when the only thing that has changed is the order of the elements.

[EricWittmann]

I think the best thing is for ordering in the UI to match the source (as mentioned) and for users to be able to move stuff around via drag & drop. That's not a trivial change but is the right thing to do IMO. Thoughts @jsenko ?

[Herrick19]

I've ran in this issue today and I see no one commented since more than 2 years.

Doesn't seem like a very popular feature request, but add my voice to it :)