News for hackers. Stuff that matters.
Re: by paholg on Monday March 25, 2024 @05:22PM (#39821408)
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.

Re: by rad_gruchalski on Monday March 25, 2024 @07:08PM (#39822298)
You can write an OpenAPI spec in JSON. You can use Jsonnet to generate your spec from whatever input you need.
Re: by madeofpalk on Monday March 25, 2024 @07:59PM (#39822702)
JSON is a different kind of yuck to have to author by hand, especially in the volume an api spec tends to be.
Re: by rad_gruchalski on Monday March 25, 2024 @08:47PM (#39823071)
Yes, so use Jsonnet or generate it from some intermediate representation using some alternative method. What’s the problem?
Re: by paholg on Monday March 25, 2024 @09:58PM (#39823541)
Why though when I can just generate it from my actual code and not have to maintain two copies of my api spec?
Re: by lttlrck on Tuesday March 26, 2024 @06:23AM (#39826081)
Jsonnet introduces another (flawed) language?
Re: by refulgentis on Monday March 25, 2024 @09:31PM (#39823396)
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.

Re: by rnts08 on Monday March 25, 2024 @06:11PM (#39821814)
Absolutely, and yes YAML is trash.
Re: by adawg4 on Monday March 25, 2024 @06:21PM (#39821889)
Which tool?
Re: by bigiain on Monday March 25, 2024 @07:14PM (#39822348)
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.

Re: by paholg on Monday March 25, 2024 @09:57PM (#39823539)
It's going to be very language/framework dependent.

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

Re: by BerislavLopac on Tuesday March 26, 2024 @04:45AM (#39825491)
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/