Earlier quoted context omitted.
We edit the OAS with Stoplight Studio, and enforce it with server-side middleware, which validates that requests and responses conform to the OAS (400s if requests don’t conform, 500s if responses don’t conform). At a previous workplace I’ve used OpenAPI Generator to generate clients and server stubs from the OAS, which is a nice approach to ensuring you’re confirming to the spec, too.
Did you have the requirements for users that you do not know want to define their own API upon your data?
I think these GQL benefits are somewhat legit:
1. Fetch in one round trip what would take multiple with REST
2. Fetch only the response fields you need
But honestly, 1 generally saves 0-1 round trips, and for 2, while response payloads are smaller, GQL requests payloads tend to be huge, so it’s largely a wash. At least in my GQL usage, they’ve been minor wins, not worth the complexity that GQL adds.