Join should put components back at the end of OAS files

[steve-nay-sage]

Describe the bug I know that technically the order of sections in an OpenAPI file doesn't make a difference, but the output of the openapi join command now has components before paths. That's unexpected for those of us who are used to looking at files in which paths comes before components. It's machine-readable and functional either way, but not as human-readable as it used to be. I'm 99% certain that the join command used to output files with paths before components.

The "normal" way:

openapi:
info:
tags:
servers:
paths:
components:  <==

Current join output:

openapi:
info:
components:   <== 
tags:
servers:
paths:

Expected behavior My "wished for" behavior is that the join command would retain the order of the original OAS files in the output OAS file, but I realize that the different input files could have the sections in different orders. So my next-best wish is that join would go back to putting the components section at the end of the file, after paths.

openapi-cli Version(s) What version of openapi-cli are you using? beta.69

Node.js Version(s) What version of node.js are you using? 14.16.0

[SmoliyY]

Hi @steve-nay-sage, Could you confirm this is still the case? I've tried it several times couldn't reproduce this case.

[SmoliyY]

Now I see, this issue can be reproduced with this example. However seems like it's likely happening because of first definition not full and invalid. I am wondering if we want to join 2 definitions if one of them permanently not full or invalid - what do you think @RomanHotsiy @adamaltman

[adamaltman]

I'm not sure. It can be valid and not full, right?

[SmoliyY]

Yes, but in case if we have '--lint' option enabled for the join command we do not exit in case if definition is invalid. I assume that in case of the --lint option we should not create result file and exit if there are any errors?

[RomanHotsiy]

I'm not sure about those above. I think what we should do is to sort top-level yaml keys before saving the output.

I think we should do it always (not only for join but for other commands as well) and do not keep the original document order.

What do you think?

[SmoliyY]

I think what we should do is to sort top-level yaml keys before saving the output.

It sounds reasonable and make sense. As for start we can go with such option.

I think we should do it always (not only for join but for other commands as well) and do not keep the original document order.

We probably will also need to apply this behaviour in the bundle command.

[IgorKarpiuk]

@RomanHotsiy In what order should we sort the keys? Maybe we can use an order like here ? What to do with custom fields, add to the end of the file ?
@lornajane Perhaps you have some thoughts on this?

[lornajane]

I think the specification order of keys is a good idea, let's do that

[RomanHotsiy]

@IgorKarpiuk specification order makes sense in general but there is some issue.

Usually people put tags, security and externalDocs right after info section. And this makes a lot of sense to me.

I would use the following order.

openapi
info
jsonSchemaDialect
servers
security
tags
externalDocs
paths
webhooks
components

[RomanHotsiy]

@lornajane @adamaltman what do you think?

[lornajane]

I usually put tags last but that is probably a matter of taste! I'd be equally happy with the order suggested here