[Recipe] Generate OpenAPI 3 specification from blitz API routes

[MrLeebo]

The original feature request: generating a HTTP client for your blitz app's API

At the last meetup, we briefly discussed the idea of a CLI command to generate an NPM package for an HTTP client from your API 💻. I thought it was a pretty good idea, if you have the kind of web app that other developers might want to get direct access to the API.

• However, let's say we produce an awesome JavaScript/NodeJS client, and there's much rejoicing! 🎉
• Then somebody wants a client for their PHP app, so they add another command to generate the PHP client... Now there's some more rejoicing. 🥳
• But who can forget about their C# and Java clients. So now you need to write those up... Hooray? 😴

Suddenly I don't feel like rejoicing anymore... 😿

Fortunately, there is an easier way to give people the ability to generate HTTP clients, as well as other utilities.

OpenAPI

A more elegant approach would be a Blitz recipe to generate an OpenAPI Specification (formerly known as Swagger docs 🕺) based on your app's API routes. Open API has a lot of tools released already to generate HTTP clients in different programming languages based on a specification.

So what does implementing an OpenAPI specification look like?

The recipe would produce an openapi.json file that gets served by the app, basically a JSON version of the API output from blitz routes.

Users could generate HTTP clients that suit their needs:

swagger-codegen generate -i https://example.com/api/openapi.json -l nodejs

Best part is you wouldn't have to lift a finger, this is a command that the developers who are integrating with your API could run.

[mtford90]

This would also be really useful for e.g. re-using the generated Blitz API in a react native app (which I will need to do in the future). Love the idea!

[Skn0tt]

Love the idea! Publishing an OpenAPI spec would be helpful for a variety of things I think. Maybe it could also be used for Static Application Security testing or similar things?

[MrLeebo]

@Skn0tt I was talking to @flybayer about this and he brought up a good point:

Even if we made an accurate specification file from our RPCs and APIs, our usage of SuperJSON is going to prevent any existing OpenAPI code generators from being able to create an effective HTTP client from it. There would need to be a port of SuperJSON in the client programming language, and right now one only exists for JS.

If we did create ports of SuperJSON in other supported languages, we'd basically have to build our own OpenAPI code generators to make use of it.

Outside of doing that, we can't really generate OpenAPI paths for RPC endpoints. We might still be able to create them for custom API endpoints, but that would narrow the scope of this feature a lot.

Perhaps RPCs should be configurable to use either SuperJSON or classic JSON serialization, and we scope OpenAPI to classic?

[MrLeebo]

Probably would also necessitate versioning of the RPC layer in case we need to make changes to the schema later.

[Skn0tt]

I'm really torn about SuperJSON adaptations for other languages - but that's a discussion for another day.

I see another big obstacle: How do we extract JSON Schema / whatever OpenAPI uses for schemas out of our TypeScript code? Queries / Mutations can potentially return arbitrarily complicated TS types, and I don't think that there's a full-coverage way of mapping them to JSON schema ...

[Skn0tt]

Apparently, typescript-json-schema does just that - would be worth looking into!

[flybayer]

We designed superjson exactly for this scenario to have a graceful fallback. So it's not something you have to turn on or off on the server. The client can choose to use all the info or not

[Skn0tt]

Related issue: #745

[flybayer]

So I found there's a thing called OpenRPC which is better suited for our RPC APIs and also supports codegen.

So we should investigate this further too: https://open-rpc.org/beginners

[MrLeebo]

Don't think this will fit our use case.

OpenRPC assumes that all of the RPC actions have the same endpoint path, doesn't support any content type except JSON, and requires errors to have a numeric error code. Blitz APIs don't follow any of those constraints.

[kn0ll]

knowing very little about your history or direction i realize there is a high risk of annoying someone with this post. if i am missing any obvious reasons this is a terrible idea, please forgive me. :)

i think the strong typing of GraphQL provides two big benefits directly relevant to the issue:

• implicit documentation
• client queries can be validated against the schema, meaning that with respect to types, any graphql client is (about?) as sufficient as a dedicated client library

the fact that Blitz is already built using a strict subset of GraphQL (object types, queries, and mutations) definitely doesn't hurt. and this is not so much relevant to the issue but still remarkable, i think if my intent was to build only a GraphQL API, i could see Blitz outperforming all of the existing GraphQL options (Nexus, TypeGraphQL, etc) in terms of DX, because of how code/dependency injection is core to the Blitz process.

to go a little off the deep end here, i could maybe imagine a world where you specify plug and play API generators for Blitz (Swagger, GraphQL) the same way you specify a form provider, or the same way you specify client generators for Prisma.

but at the end of the day, the "zero API data layer" is really the crown gem of Blitz so i hope i never have to actually use the thing we're talking about! :) but i understand the necessity of a catch-all.

[flybayer]

Thanks! Yeah early on we discussed using graphql instead of RPC. We didn't go with graphql then because (1) generating the gql schema without explicitly defining it is a hard problem and (2) we're aiming to be ideal for serverless use case and graphql is sort of anti-serverless since it requires one single large lambda which can quickly run into scaling issues.

But it's still a possibility to switch to graphql internally. If anyone wants to prototype it, that'd be great! (but note our currently RPC implementation code is going to be shifting with the planned next.js fork)

[kn0ll]

i had considered (1) a not-impossible challenge... but i admit i hadn't considered (2). it would be a great option for people who are using not-serverless, but i understand why Blitz would not offer it. thank you.

[MrLeebo]

And to be clear, just because Blitzjs doesn't offer a GraphQL option out of the box doesn't mean that you can't just create your own API route and serve GraphQL from it. If that covers all of the goals that you're looking for from OpenAPI 3 and you're not worried about the serverless part, then by all means go for it! 🚀

[MrLeebo]

Setting up graphql is even better when it's a blitz recipe.