Can TypeSpec Be an Alternative to OpenAPI?
Switching from OpenAPI to TypeSpec might be a viable solution.
On its own, OpenAPI isn't adequate for generating sophisticated code. At least, that's what engineering teams from Elastic and Pinterest think. Teams like these have been replacing OpenAPI with other better solutions throughout most stages of the API lifecycle. It's natural that engineers want to optimize their work. I mean, wouldn't you? Whenever they find something that could be done better in some other way, they make changes. And that's what I see trending now with respect to OpenAPI. So, if the idea is to replace OpenAPI with something else, can that something else be TypeSpec? Read on to find out.
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
TypeSpec is not perfect. But its shortcomings are bearable compared to what you can gain by using it. Among its biggest selling points are its ability to define complex data types using strong typing, its developer-centric design offering easy code-driven API definition, and its multiple target generation, including client SDKs, OpenAPI documents, and even infrastructure configuration. If you're a developer, TypeSpec feels like a glove. Between writing code and having to define your API using YAML, what would you prefer? This is why many teams are adopting TypeSpec as their source of truth for API definition.
Pinterest has one of those teams. I learned about it from Mark Cerqueira, a Senior Director of Engineering, who shared that they want "TypeSpec to provide a unified schema for all of their API customers." From an engineering perspective, having a single source of truth and then generating OpenAPI and GraphQL definitions makes a lot of sense. They're heavily invested in making it happen as they have a dual usage between REST and GraphQL, depending on whether the consumer is external or internal.
They believe in this vision so much that they've been officially collaborating with TypeSpec on building what is called an "emitter" for GraphQL. According to the documentation, "emitters are libraries that utilize various TypeSpec compiler APIs to (...) generate artifacts." And those artifacts can be anything. While emitters for OpenAPI, JSON Schema, and Protobuf are already included, anything else has to be added. That's exactly what Cerqueira's team has been doing with GraphQL. And they're not the only ones. If you look around, you can easily find TypeSpec emitters that aren't part of the official distribution. But, even without a specific emitter, you can always use OpenAPI as a bridge to generate almost any kind of artifact.
Let's say you want to generate a good-looking reference for your REST API. The workflow is quite simple. First, you define your API using TypeSpec, taking advantage of it being strongly typed. Then you use the OpenAPI emitter and generate a full description document. With the OpenAPI document, you pick your favorite API reference generator, feed it the generated description, and voilà, you get your good-looking reference. The only thing to pay attention to is that you shouldn't edit the OpenAPI document because that's not the source of truth. Instead, whenever you want to make changes, you should go back to the original TypeSpec definition and then run the OpenAPI emitter.
The area with the highest number of TypeSpec emitters is code generation. There are official emitters for client and server code generation in programming languages such as C#, JavaScript, Java, and Python. Other third-party emitters let you generate code for languages and frameworks like TypeScript, Express.js, and Flask. Creating your own emitter shouldn't be too complicated. TypeSpec offers extensive documentation for its emitter framework and, in particular, for the code generation part of it. A big part of the work of generating code is done thanks to Alloy, a framework for providing "highly ergonomic and productive" code generation. As you can see, you're in good hands if you decide to build your own emitter.
So, is TypeSpec a viable alternative to OpenAPI? I'd say that TypeSpec is more than an alternative to OpenAPI. You can easily use TypeSpec as the source of truth for definition and, in addition, use your preferred API format for interacting with tools and consumers. Using TypeSpec with OpenAPI, for example, feels like an extremely powerful combination.