4 ms·
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 t
by paholg 3y ago
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.
- rnts08 3y agoAbsolutely, and yes YAML is trash.
- adawg4 3y agoWhich tool?
- bigiain 3y agoI'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 3y agoIt's going to be very language/framework dependent. I'm using aide for a Rust/Axum server: https://github.com/tamasfe/aide https://github.com/tamasfe/aide
- rad_gruchalski 3y agoYou can write an OpenAPI spec in JSON. You can use Jsonnet to generate your spec from whatever input you need.
- madeofpalk 3y agoJSON is a different kind of yuck to have to author by hand, especially in the volume an api spec tends to be.
- rad_gruchalski 3y agoYes, so use Jsonnet or generate it from some intermediate representation using some alternative method. What’s the problem?
- refulgentis 3y agoI 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.
- BerislavLopac 3y agoYou 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/ https://stoplight.io/