search

IBM / openapi-to-graphql

Translate APIs described by OpenAPI Specifications (OAS) into GraphQL
https://developer.ibm.com/open/projects/openapi-to-graphql/
MIT License
1.61k stars 211 forks source link

Smarter object type name generation #9

Open ErikWittern opened 6 years ago

ErikWittern commented 6 years ago

The way that we name new GraphQL Object Types (GOTs) right now is highly varied. All our names are generated from the OAS. Sometimes the name is part of a reference, sometimes it is the name provided by the schema, and sometimes it is a combination of the path and the method. We choose based on the information we have on hand but otherwise, the processes are simple. Because of the different ways we use to generate names, our names lack uniformity. A greater problem is that sometimes, we will end up with long and ugly names.

If we can use smarter methods to create names, hopefully we can create a nicer interface.

Some ideas include: analyzing descriptions for keywords, comparing field names with similar field names in other OASs, and improving the simple parsing that we do already (e.g. getUsers -> users).

tbrannam commented 5 years ago

OpenAPI has a 'operationId' which would be a good place to start with naming queries and mutations. Would be nice to allow those to be driven from the specification - allowing decoupling from the name of the return type.

ErikWittern commented 5 years ago

@tbrannam Thanks for the input! We specifically decided against using operationIds (for queries) as this route often leads to non-idiomatic GraphQL interfaces, where fields would be called getUser rather than user.

Decoupling is still possible currently with OASGraph: you can simply rename the JSON schema definition, if it is referenced in the OAS, and OASGraph will reflect the schema's name.