Use the code to do the design. Don’t implement the damn thing. Just work in a nicer medium like Typescript. Add attributes. Remove attributes. Move things around in the refactoring tool. Then generate the doc. Forget about the whole “this is what the database does” stuff.
Thanks. I missed this part https://openapistack.co/docs/openapi-backend/typescript/ so the types are generated for the backend to use. We’ve used API first approach before, but it was very painful to keep the types in sync. Now we’re transitioning to FastAPI which allows to more or less create the OpenAPI types in code (via pydantic which can export the python types into OpenAPI schema).
We now follow a kind of hybrid approach in which the routes and types are created in code first, without actual implementation (just return 404). This auto generates the spec.yaml as well as any vendor code we might need (via client generator). I think this is quite a productive workflow as well because the type generation in code is more convenient than typing yaml by hand and everything is always in sync
The code first approach is surely enticing and miles better than manually keeping the openapi spec up to date.
But I’d always advocate for going schema first. This has huge benefits for collaboration between frontend and backend engineers and results in better designed APIs and generally better software in my experience.
Maybe I didn’t explain the process correctly, we do generate the spec first, it’s just that the tool we use for creating the spec is the code that will later contain the implementation.
I think the point is, graphql apis tend to be so flexible that it’s easy to accidentally ship an API that allows clients to craft excessively heavy nested queries in a single request.
Supporting nested queries isn’t really a common thing in REST, and it’s simpler to rate limit clients by resource than query complexity.
If I'm understanding coding123's comment correctly, I think AsyncAPI would need to be extended to allow specifying a GraphQL schema and not just a JSON schema as the message payload and (I guess implied?) response types
Thank you for your encouraging words and insights!
There are indeed popular DSLs and code to openapi solutions out there. Many of which are easy to plug in to the openapi-stack libraries btw!
I guess I personally always found it frustrating to try to control the generated OpenAPI output using additional tooling and ended up preferring yaml + a visualisation tool as the api design workflow. (e.g. swagger editor)
But something like https://buildwithfern.com, or using zod as substitute for json schema may indeed be worth a try as a step before emitting openapi.
Good point, and one that counts towards ts-rest atm; If you're bringing your own OpenAPI spec, there is (not yet) an OpenAPI->Zod converter available.
The great thing about OAPI is there's _so much tooling_ available, but it can be daunting and very frustrating to find the "right one". I spent more hours than I'd care to count wading through the ecosystem,
Perhaps it'd be a good idea to promote a few tools via your project? I suspect many potential users would fall off early because they (imo wrongly) believe the upfront cost of writing the OAPI spec is too much to ask. I do understand the reaction if they don't know of good DSLs, though.
PS: ts-rest's video on the front page is what immediately convinced me to try it out. Your current interactive example is nice, _but_ it doesn't product type errors for me so the value isn't as immediately obvious (I'm assuming watch doesn't work in the sandbox?).
Speaking personally as a full stack engineer, unless the backend is completely trivial to implement I find it much faster and more efficient to write and iterate JSON schema while implementing frontend features than actually implement backend logic first.
