Write OpenAPI with TypeSpec
blog.trl.sn
Write OpenAPI with TypeSpec
1–10 of 74 posts
Re: Write OpenAPI with TypeSpec
#2This is typical Microsoft - overly complicated solution in search of a problem. Yaml and Json are beloved for a reason - they're simple and effective.
Re: Write OpenAPI with TypeSpec
#3Writing OpenAPI by hand sucks, this looks fantastic. The only reason I prefer generators from code comments is because the structure and the code itself live in the same place, so it's harder to forget.
Re: Write OpenAPI with TypeSpec
#4Looks interesting. Can it handle asyncapi specs too?
We use boats (npm) to define our openapi and asyncapi specs which uses file based structure to separate definitions for models, paths, params etc into separate files which makes it much more maintainable. Native refs make it super easy to reuse definitions, and you can write custom helpers in js to abstract things like the Page definition in that example.
Having a shared templating language for openapi / asyncapi specs which is ergonomic and can be used by more than just JS devs is a great idea. I'll keep an eye on this project.
Re: Write OpenAPI with TypeSpec
#5This is typical Microsoft - overly complicated solution in search of a problem. Yaml and Json are beloved for a reason - they're simple and effective.
I think "beloved" is a bit of a stretch... tolerated perhaps, for their simplicity and versatility, in that you can make them work for most kinds of data transfer and configuration if you don't mind shoehorning your needs into that spare box. But beloved? hardly...
Re: Write OpenAPI with TypeSpec
#6Looks interesting. Can it handle asyncapi specs too? We use boats (npm) to define our openapi and asyncapi specs which uses file based structure to separate definitions for models, paths, params etc into separate files which makes it much more maintainable. Native refs make it super easy to reuse definitions, and you can write custom helpers in js to abstract things like the Page definition in that example. Having a…
Hey, author here. Right now we don't have any streaming or eventing support, but I am working on it as we speak. My first goal is to support describing SSE and JSONL HTTP streaming endpoints, but I want to work toward an AsyncAPI emitter as a peer for our OpenAPI emitter.
Re: Write OpenAPI with TypeSpec
#7I wonder why this isn't written in Typescript directly so as to handle documentation, validation and type definitions in one go.
Especially if you want to reuse type definitions of objects elsewhere in your code.
An API request or response usually do not contain the exact model attributes. Only the public facing ones which are then often filtered down some more, depending on the user making the request (and their roles, groups, permissions).
Re: Write OpenAPI with TypeSpec
#8Wow, I was _just_ thinking that it would be excellent to have something like this the other day.
I really prefer spec-first development, since it gives other developers an opportunity to review the API _before_ the changes start being implemented, and trying to do this from a codegen-based OpenAPI implementation frequently leads to the PR being "broken", since you've only changed the signature of all your methods and not the implementation yet.
But changing a big OpenAPI yaml file is really hard to easily review, and breaking it up into included files only helps a little, honestly. We can compile the new spec and host the HTML in a temporary location to make it easier to view what the new spec will look like, but once you've done that, you're no longer looking at the diff of what's changed.
TypeSpec looks terse enough to be easy to review (and to write!) which really looks like it'll help with that. I'll have to mess around with it in some personal projects of mine with reasonably-complicated specs and see if there's no obvious speedbumps first, but I'm hoping not, because I'd love to start using this in all the projects I'm contributing to!
Re: Write OpenAPI with TypeSpec
#9This is cool! I made a similar project to this one when we switched from GraphQl to regular REST at $work but decided to drop it since I didn't have the bandwidth to work on it.
I see editor support for VSCode, but is it backed by an LSP or is it VSCode only?
Re: Write OpenAPI with TypeSpec
#10Question for the author, why not fully adopt TypeScript? Ie have TypeSpec be a well-defined, limited subset of TypeScript? At first glance, it seems to me that a model maps to an interface, an op is a function, and an enum is a string literal union.
I understand that you can’t express everything that way, eg annotations, but you could get pretty far with putting those in JSDoc comments, no? I could see a big practical benefit to TS code being able to read an API spec directly without another conversion step, so I’m curious why you chose not to go with that.