Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Write OpenAPI with TypeSpec

blog.trl.sn

Post reply on HN
Print view View original

31–40 of 74 posts

Re: Write OpenAPI with TypeSpec

#31

Post by Alupis »

buzziebee wrote: post #4

Looks 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…

My biggest frustration when working with AsyncAPI is how different it's bundling logic is versus OpenAPI tooling, like Redocly.

They're both based on JSON Schema, but AsyncAPI's bundling logic seems to fall down a lot when facing `$ref` in strange places (even though the actual spec allows), such as ref'ing an entire channel or operation.

Looking at boats, it looks a lot like regular open/async api spec documents, with a few features sprinkled in. How great is the transpiled output? Does it pass standard validators provided by OpenApi and AsyncApi? Does it support AsyncApi 3.x?

Re: Write OpenAPI with TypeSpec

#32

Post by mnahkies »

bterlson wrote: post #28
mnahkies wrote: post #24

Earlier quoted context omitted.

Yeah I'm also on the schema first side of the debate. I think for me it comes down to a few key points: - APIs are forever, the choice of language/framework is an implementation detail - Constraining yourself to what can be represented in the specification is better than generating a specification from implementation that may not be capable of expressing the full details - When working with diverse languages it provi…

Hey, nice work on openapi-code-generator, its output is very nice. I think you could probably package it up as a TypeSpec emitter without too much difficulty, by emitting OpenAPI and feeding it to your generator. I am doing a similar thing for a Kiota emitter I'm working on. We recently added an API to get the OpenAPI as a JS object which may be of help in this quest: https://typespec.io/docs/libraries/openapi3/refer…

Thanks for the reference! This is essentially what I had in mind - allow typespec as input and transparently convert to openapi then feed to the existing process.

I suspect there's potential for some loss of information with this approach (I'm relatively new to typespec so not sure) but I plan to do this as a first pass and then consider a more direct approach later if I see gaps worth fixing.

Re: Write OpenAPI with TypeSpec

#33

Post by beders »

tyayers wrote: post #2

This is typical Microsoft - overly complicated solution in search of a problem. Yaml and Json are beloved for a reason - they're simple and effective.

Yaml is beloved when it's maybe two pages of little indented config.

It becomes a nightmare once people try to emulate a DSL with it.

Re: Write OpenAPI with TypeSpec

#34

Post by ramilefu »

I've been toying with the design of something similar here and there over the past couple of months. It never made it past the pen-and-paper stage though. Pleasantly surprised to find this today and will have to try it out for a work project.

My original motivation was the lack of OpenAPI definitions across projects, despite everyone agreeing their existence is a "best practice". As you suggest, developers just truly hate writing them. Unfortunately, even the "generate it from code" approach tends to be complicated and often feels duct-taped together.

Re: Write OpenAPI with TypeSpec

#35

Post by zexodus »

TypeSpec is great, but if you're working with Rust and you're about to write a new project that will require an OpenApi spec sooner or later, I'd like to recommend a web framework that has spec generation baked in:

https://github.com/poem-web/poem (see poem_openapi)

All you need to do is derive a trait on your response structs and in return you get an almost perfectly generated spec. Unions, objects, enums are first class citizens.

Also, if you're from coming from PHP, the controllers feel very much like symfony controllers.

P.s. Please do recommend an ORM that would feel closer to doctrine. I miss doctrine.

Re: Write OpenAPI with TypeSpec

#36

Post by mmcclure »

We're also spec-first at my co (pretty mature, large API surface area), but maintaining the OpenAPI spec in YAML is extremely annoying and tedious. This checks a lot of boxes in terms of being interesting, but what does the path from an existing YAML spec to TypeSpec look like? In an ideal world we could just ingest our OpenAPI spec, get the TypeSpec version out, then be able to clean up/iterate from there.

I didn't see anything in the docs, but I would love for someone to tell me this exists.

Re: the post itself, this was much more compelling than TypeSpec's website imo. At the very least it feels like some of these examples, such as the enum bit, should be ported there. Also interesting that there isn't a single mention of languages like Cue[1].

[1] https://cuelang.org/

Re: Write OpenAPI with TypeSpec

#37

Post by bterlson »

mmcclure wrote: post #36

We're also spec-first at my co (pretty mature, large API surface area), but maintaining the OpenAPI spec in YAML is extremely annoying and tedious. This checks a lot of boxes in terms of being interesting, but what does the path from an existing YAML spec to TypeSpec look like? In an ideal world we could just ingest our OpenAPI spec, get the TypeSpec version out, then be able to clean up/iterate from there. I didn't…

It does not exist, but it will be worked on fairly soon. You can track progress on GitHub [1]. It will be as you suggest - a one time conversion, after which you can iterate. We have this workflow for inside Azure, but the converter is Azure-specific (e.g. converts to TypeSpec that uses our extensive Azure-specific component library). It will take a bit to generalize.

[1]: https://github.com/microsoft/typespec/issues/3038

Re: Write OpenAPI with TypeSpec

#38

Post by dajonker »

We have been using this for a couple of months now and it works really well. It's so much better than writing OpenAPI by hand, and I never ever will do that again after working with TypeSpec.

Thank you!

Re: Write OpenAPI with TypeSpec

#39

Post by hocuspocus »

lijok wrote: post #18

What are people's thoughts on this vs AWS's Smithy? We've been looking to buy into Smithy heavily as we no longer have the appetite to deal with OpenAPI and it's horrendous ecosystem.

I would pick Smithy if I had to go spec-first.

I currently tolerate OpenAPI because I'm using a robust code-first approach (Tapir in Scala) on the server side, but I otherwise agree, the ecosystem seems brittle.

Post reply on HN