Should OASGraph support GraphQL code-generation?

[ErikWittern]

Currently, OASGraph builds up a GraphQL schema including corresponding resolve functions in memory. I think this approach is great for immediately serving the GraphQL interface.

However, having the GraphQL schema in-memory only also has drawbacks:

• In some settings, the GraphQL schema needs to be re-generated repeatedly. For example, in serverless, it needs to be re-generated for every invocation, which adds around 100 ms for a relatively small OAS.
• Generated schemas can mostly be used as-is. However, OASGraph may also be considered a starting point for developers to create a GraphQL interface, which they can then extend and maintain.

In consequence, it may be desirable for a library like OASGraph or thereupon-based tools to output source code instead.

One question is whether this would require a dedicated, separate effort, or can be integrated with a library like OASGraph? On the one hand, generating code requires different capabilities from those supported by OASGraph, including templating and writing to file. On the other hand, capabilities present in OASGraph may be re-usable, for example the schema already produced by OASGraph could simply be stringified, or sanitation mappings could be reused.

[marioestradarosa]

@ErikWittern , I am reading more about GraphQL and your library and I am still very impressed on your work and its purpose, it seems like there was no other solution so far like this 💯 . It seems like creating the GraphQL schemas, types, resolvers is something that might be preventing a percentage of developers not adopting the technology to build servers.

For example, in serverless, it needs to be re-generated for every invocation,

What condition changes on this approach for a need to regenerate it again?

[ErikWittern]

@marioestradarosa We played around with OASGraph in combination with IBM Cloud Functions in the past. Given they are stateless, upon receiving a request, the Cloud Function would start up, use OASGraph to create a schema on the fly, and use it to process the query in the request. Given OASGraph generates the schema in memory, we saw no other way of doing this.

[marioestradarosa]

Generated schemas can mostly be used as-is. However, OASGraph may also be considered a starting point for developers to create a GraphQL interface, which they can then extend and maintain.

I see another option coming --save ? , that would save the schema locally for off-line editing by the developer. (ie: openapi.json fetched and openapi.schema generated).

[marioestradarosa]

Given they are stateless, upon receiving a request, the Cloud Function would start up

Thanks for the details, that makes sense for this scenario.

[ErikWittern]

@marioestradarosa I really like the idea for a --save option for the CLI. The fact is that after running OASGraph, we have a GraphQLSchema object, which we can easily combine with the printSchema utility provided by GraphQL.js.

So, if a developer would chose --save, do you propose that the server will actually not be started, but the schema be saves / printed instead?

I also wonder whether to output the schema to a file, or maybe print it to the console, from where it can also easily be saved using Unix redirections.

[marioestradarosa]

do you propose that the server will actually not be started

No, because --save would just mean I don't mind starting the server but I just want a copy of the schema to open it with an editor.

which we can easily combine with the printSchema

[ErikWittern]

Ok, makes sense to also start the server. In that case, I think --save should actually save the schema to file (in the current folder) and inform the user about it.

Simply (JSON) stringifying the GraphQLSchema results in a for humans rather unusable JSON document, for example:

{
  "_queryType": "Query",
  "_directives": [
    "@include",
    "@skip",
    "@deprecated"
  ],
  "_typeMap": {
    "Query": "Query",
    "String": "String",
    "User": "User",
    "__Schema": "__Schema",
    "__Type": "__Type",
    "__TypeKind": "__TypeKind",
    "Boolean": "Boolean",
    "__Field": "__Field",
    "__InputValue": "__InputValue",
    "__EnumValue": "__EnumValue",
    "__Directive": "__Directive",
    "__DirectiveLocation": "__DirectiveLocation"
  },
  "_implementations": {},
  "__allowedLegacyNames": []
}

In contrast, printSchema will result in something like this:

type Query {
  user(id: String): User
}

type User {
  id: String
  name: String
}

[marioestradarosa]

what do you think would be the name for the output file?
[ ] oasgraph.graphql [ ] oas2graphql.graphql [x] schema.graphql

[Alan-Cha]

Personally, I think it makes more sense not to start the server.

I don't think users will need to generate the GraphQL schema often so if the intention of running the server immediately after is to save users' time doesn't make much sense to me. If I wanted to save the GraphQL schema, my main objective would be to study the schema rather than starting a server. I feel like starting the server is doing a lot more than what the average user will want and starting up a server is potentially more costly than the effort to rerun oasgraph.

However, I'm not strongly opposed to starting the server so I am fine either way. Just wanted to express my thoughts.

[marioestradarosa]

If I wanted to save the GraphQL schema, my main objective would be to study the schema rather than starting a server

@Alan-Cha I agree.

[llamaferoze]

Honestly, I'm not too sure how to begin. Code generation is something completely new to me.

Graphback (the project I'm actively maintaing) will have some code generation capabilities and it is already integrating with OtG.

npm install -g graphback-cli
graphback init yourproject
graphback openapi yourapifile.yml
// Review your graphql model and add extra ID's that might be needed.
graphback generate
graphback db 

Documentation: https://graphback.dev/docs/openapi

This is a database migration workflow. We are also working on RESTFULL API path - I have a raw spike for that use case that we postponing because of the reachitecture that is happening currently. Maybe we can simply provide some reusable modules in Graphback and see if we can simply import them inside OtG without bringing some complex libraries to the core.

WDYT?

Continuing the discussion from the previous thread. https://github.com/IBM/openapi-to-graphql/issues/253#issuecomment-534613868

@wtrocki graphback is an interesting library, how does it compare to OtG? Do you use OtG in graphback?

[wtrocki]

Graphback using now OtG but only for translation from the OpenAPi to GraphQL file. Capabilities are already there is is just to integrate them into OtG.

In current form graphback library can be used as dependency to OtG and provide code generation workflow out of the box utilizing amaizing api translation engine OtG has. I would love to see how we can extract some use cases we see in community (graphback is fully community driven project for the moment)

[wtrocki]

If we forget about graphback. There are a number of code generators available for both OpenAPi and GraphQL that can be employed. I think is best to first get the use cases of the workflows that should be supported. There is also problem with the language (JavaScript/TypeScript/Flow etc.) so it will definitely need some specification and serious thoughts.