Thread by @philsturgeon

In ye olden days you needed to write API descriptions by hand, in text, with a keyboard, which took FOREVER.

These days there are awesome GUI Editors, and an interesting new generation of OpenAPI-aware frameworks are appearing, like annotations but good. dev.to/philsturgeon/t…

This cover image, which has been cropped funny and wont be removed, is a visual depiction of how useful Annotation/Comment-based tools usually are.

I got a mention in @libel_vox's awesome tinyletter.com/NetAPINotes/ for this.

tl:dr; Do not confuse proximity with accuracy

The only disagreements I've had with this article were "Um, well achtually, you don't have to write it ALL by hand, you can copy and paste some stuff to speed you up!"

Ooof. I mean, you CAN, but using $ref to split things up is way more useful. stoplight.io/blog/keeping-o…

If you’re paying for tools which force your team to memorise nested YAML structures then probably start looking at some more modern tools which have moved beyond ye olden days.
- Several: openapi.tools/#gui-editors
- The one I work on: stoplight.io/studio/
#ApiDesign @OpenApiSpec