-
Notifications
You must be signed in to change notification settings - Fork 38
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Models: Writing Node reorders Operations #643
Comments
Hi @zaiddabaeen thanks for the question. What you are asking for is possible but requires some thoughtful changes to the code generator we use. As you observed, the models and much of the functionality (readers/writers) are now being generated from those spec files. So we would need to add a new feature of some kind to the code generator (and ultimately the generated models) to allow for this. The code generator project is here if you wanted to take a look: https://github.com/Apicurio/apicurio-unified-model-generator/ If you had a proposal based on how you would want the generated models to be changed so that the writer would do what you want, that might be a good start. Then we could figure out how the spec files and code generator could perhaps support that target. |
I would also be interested in @MikeEdgar 's thoughts on this! Also @zaiddabaeen can you describe a little bit more what the use-case for needing this is? Are there downstream tools (eg documentation generators) that do something different depending on the ordering of those properties? I'm not quite convinced this is a desired behavior. :) |
I definitely see both sides of this. One one hand, the user input should be preserved as closely as possible when passing through the model. One the other hand, the ordering of map entries shouldn't really matter. That is, ordering seems like more of a UI/display concern. As far as a solution, making the operations a |
@EricWittmann indeed it is for UI/display purposes for API Reference generators (that take in an API definition and create a web page for developers to explore it). I agree with you @MikeEdgar that user input should be preserved as much as possible. I'll need quite some time to get familiar with the model generator to propose how the writer needs to be changed. |
I don't know if putting the operations into a LinkedMap is the right approach, but it would work of course. The code generator doesn't currently support generating models in that way. Because the operations are direct properties of the PathItem entity (as defined by the spec) rather than a collection/map of named children, the generated model just has each property as a field. Another option would be to maintain some sort of additional collection that would serve as a "hint" to the writer. The generated Setter methods would need to be changed to maintain that collection, and then the generated writer would need to use the hint when writing the output. Either approach is probably messy from a codegen perspective. I guess the use-case here is to preserve the ordering from the original file, and also preserve ordering whenever the library is used to add new operations to path items. Is that correct? Another (maybe not great) option here would be to use a vendor extension (e.g. |
This is basically what I was thinking also. Each HTTP method would still need it's own accessor/mutator method, but internally it would be stored in the map (or maybe an insertion-ordered list with the keys as I think you're suggesting). I agree this would be messy for generated code. |
When saving an OpenAPI spec using ApiCurio, the order of operations is forced. This is because of how
writePathItem
is implemented, where it checks if the node has "get", writes it, then "put"... then "post"... As seen in the generated ts file OpenApi31ModelWriter.ts:I understand that all of the models are generated from
resources/specs/openapi
, which makes it really hard to modify how this works.Is there a way to override this function's implementation with one that iterates over the key/values and writes them, so no order is enforced?
Would be happy to write a PR if there's a way to do this.
Motivation:
Some of our users of the editor wish to follow the the example of larger companies in how the operations are ordered in their API references, where creating resources goes first, then reading them, them updating them, then deleting them - as they report that this is the natural way of reading an API spec, as to read resources, they should be created first.
Related: Apicurio/apicurio-studio#1677
The text was updated successfully, but these errors were encountered: