Query type - irregular naming convention

[dougal83]

One thing irks me about the current output of oasgraph is that we have query types with numbers added to the end.

Using this example openapi schema from lb4.

Current behaviour

We return a query such as 'Todos3'.

Expected

A consistent naming convention. 'Todos' Alternatively attaching the verb to avoid naming collisions? e.g: 'TodosGet'.

Discussion

I find that the openapi-generator schema produces my idea of an expected naming convention. For the above openapi schema we get the following: graphql schema.

Is this something that can be improved or unnecessary as you see it?

[Alan-Cha]

@dougal83 Thanks for the feedback! I think appending the verb at the end of the type name is an option that we can add. Some users might find it useful. However, I do not think this will solve the core issue.

What I mean is that even if we do append the verb at the end of the type name, in regards to some schemas, we will still need to add a number at the end as well, e.g. TodosGet2 or Todos2Get.

I believe that OASGraph does indeed have a consistent naming convention. Perhaps it is not immediately obvious and needs better documentation so I will try to give some insight here.

OASGraph creates object types based on the operation's preferredName and the response schema. We run into trouble when two or more operations share the same preferredName but have different response schemas.

Although I have not taken a close look at the example openapi schema you have linked, I assume that in this schema, there are multiple operations that have the same preferredName and different response schemas, leading to operation types: Todos, Todos2, and Todos3.

If all we do is append the verb to end of the preferredName, these collisions can still happen. Perhaps in this OAS, we will have nice names but in others, this problem can still be present.

---

One way we can counteract this ugly naming is to use the operationIdFieldNames option. This allows a user to manually specify the field names by changing the operationIds in the OAS.

Alternatively, a user can try to collapse schemas with the same preferredName. If all operations with the same preferredName use the same response schema, then this problem will be solved. However, this could be quite involved and may lead to schemas with lots of optional fields. One potential route that we may take OASGraph is to do automatic schema collapsing, however we are still not so sure about that.

---

I need to take a deeper look into the links you have provided but to summarize, appending the verb at the end of a field name is an option that we can add but it will not solve the problem of adding a number to the end of a field name if there are still preferredName collisions.

[dougal83]

@Alan-Cha Thank you for the response and insight.

I might have used the wrong term to call it irregular but I was trying to allude to the seemingly rapid path to adding a number postfix to avoid collisions. This is a simple oas, just seemed a bit too early to hit the naming collisions.

I see your point on adding the verb will not solve due to the current implementation.

So we have three paths (assuming that these paths are 'preferredName's) that return todos1-3.
/todos/count
/todos/{id}
/todos

As matching with the response schema it will deliver three sets? I see, it is thorough I guess to account for all possibilities according to the spec.

Using "operationIdFieldNames" does provide a consistent(in line with expectation that is) result. I could live with the labels it provides but not ideal in my eyes.

Ideally I'd prefer to see type naming closer to 'openapi-generator schema' from what I've see so far. However they might struggle down the line with regards to more complex schemas. Do you have any testing oas' that I can run against the other generator? I'd be interested if their naming convention works to a point and then falls back to something like the number postfix.

Out of interest, do you have an oas/example that necessitates matching the prefered name to a response schema? (If I've understood that correctly).

Thank you for your time.

EDIT: Thinking about schema collapsing, perhaps the other generator handles that? If they do, maybe it can provide inspiration. Happy to run oas through it to save you the effort.

[Alan-Cha]

@dougal83 Yeah, it is unfortunate that the LB4 example does not work perfectly with OASGraph. For sure, the end result is 100% usable but it could be prettier. This is because OASGraph originated from IBM Research and it is designed to be a generic solution to wrapping APIs in GraphQL rather than a custom LB4 designed one. OASGraph is still being maintained by the IBM Research team and so. we are still striving towards that perfect compatibility.

---

assuming that these paths are 'preferredName's

That is the general idea, that a few different operations have the same preferredName but have different response schemas, leading to less than ideal object type names but for the sake of correctness, I just wanted to point out that selecting the preferredName is a bit more complex than selecting a name from the path, although it is one of the heuristics we use.

You can see the source code here.

Ideally, the name would come from a reference, i.e. stored from a reusable component. This goes back to the point I made about collapsing schemas. If all these operations shared the same schema, then their return type would all share the same name.

---

As matching with the response schema it will deliver three sets?

I am not sure if I understand this correctly but the problem is that multiple operations have the same preferredName but different schemas.

In this specific case:

• GET /todos/{id} receives the Todo object type
• POST /todos receives the Todo object type
• PATCH /todos receives the Todos object type
• GET /todos/count receives the TodoCount object type
• GET /todos receives the Todos2 list type, returning an array of Todo object types

It will get even more complicated with the fillEmptyResponses option.

---

To be honest, this is not the full picture. You have been asking about field names while I have been talking about object type names. I did this because query field names (mutation field names are handled differently) come directly from the object type names. However, more problems can arise if multiple query operations (GET operations) have the same return type because field names must be unique.

I don't know if you want me to get into that as this conversation is getting quite in depth but I would be happy to do so as I think it's important for our users to understand OASGraph to use it to the best of its potential. The reason why it's so complex is that wrapping APIs in GraphQL is a very complicated problem. I hope to write an "OASGraph Cookbook" in the near future to help people understand the intricacies of this problem and using OASGraph.

---

Do you have any testing oas' that I can run against the other generator?

Yes! You can find our Example API here. We have two other example APIs but they are used for specific purposes (Example API 2 for testing the operationIdFieldNames option and Example API 3 for testing creating interfaces from multiple APIs and creating links between them). Something to keep in mind is that the Example API is not very well designed on purpose. That is because we are trying to make sure that OASGraph is robust.

You can also run the Example API by running:

node packages/oasgraph/test/fixtures/example_api.json

---

necessitates matching the prefered name

I'm not sure if it's necessary to match preferredNames in order to wrap APIs in GraphQL. It just allows us to reuse object types. It also allows us to do interesting things with links, which are necessary if you want to produce a rich GraphQL interface.

---

Thinking about schema collapsing, perhaps the other generator handles that?

Thanks for the tip! I will definitely take a look into it! For now, we are focusing on creating more documentation and fleshing out our multi-OAS feature. Collapsing schemas also presents a whole host of challenges and scoping problems so it is currently on the backburner.

---

No problem! I'm happy to answer any questions you have. I really want to make people enjoy using OASGraph!

[dougal83]

@Alan-Cha Thank you for the explanation. I do find it very interesting gaining insight into how oasgraph is working. I'll definitely read the cookbook when you publish it. I'll not push you for any in depth discussion atm.