On: Show HN: Auto-generate an OpenAPI spec by listenin...

[paholg]

I don't want to write OpenApi. Yaml is a terrible programming language, and keeping it in sync with actual code is always a nightmare.

I've been using a tool to generate OpenApi from code, and am pretty happy with that workflow. Even if writing the API before logic, I'd much rather write the types and endpoints in a real programming language, and just have a `todo` in the body.

You can still write API-driven code without literally writing OpenApi first.

[rad_gruchalski → paholg]

You can write an OpenAPI spec in JSON. You can use Jsonnet to generate your spec from whatever input you need.

[madeofpalk → rad_gruchalski]

JSON is a different kind of yuck to have to author by hand, especially in the volume an api spec tends to be.

[refulgentis → madeofpalk]

I don't like writing structured formats by hand either - at some point, you either need to, as they say in France, split or get off your seat

Either don't write it by hand, i.e. use a generator for the structured format, as the comments advocate for and article is about.

Or, just say you'll never have a spec.

[rad_gruchalski → madeofpalk]

Yes, so use Jsonnet or generate it from some intermediate representation using some alternative method. What’s the problem?

[paholg → rad_gruchalski]

Why though when I can just generate it from my actual code and not have to maintain two copies of my api spec?

[lttlrck → rad_gruchalski]

Jsonnet introduces another (flawed) language?

[BerislavLopac → paholg]

You are correct about YAML, but OpenAPI is not YAML -- it just commonly uses it as for the textual representation. As others mentioned it, JSON is an alternative, although it doesn't make it much easier to write the code directly.

Sadly, there is a distinct lack of tools to make spec-first development easier. At the moment, Stoplight [0] is the only game in town as a high quality schema editor, but it requires payment for any more significant usage.

[0] https://stoplight.io/

[rnts08 → paholg]

Absolutely, and yes YAML is trash.

[adawg4 → paholg]

Which tool?

[bigiain → adawg4]

I'm thinking using this tool, and having your test suite run through it might work?

At least for people comfortable with doing test driven development.

Write your requirements for your API-driven code as tests first, then document those APIs by running the tests through this tool.

[paholg → adawg4]

It's going to be very language/framework dependent.

I'm using aide for a Rust/Axum server: https://github.com/tamasfe/aide