I use Markdown for note taking, and for personal documentation, most of my SOP/MOP are Markdown based with scripts embeded, I am sure you use it as well, at least in your Git issues, but when it comes to API design with Markdown doesn't seem to be the best choice.

Markdown or YAML/JSON - what's the right tool for your API design?

API development has come a long way, and with it, so has the demand for tools that make it easier to design, document, and maintain APIs. Two notable names that developers often encounter are API Blueprint and Swagger (also known as OpenAPI). These tools, while different in their approach, both aim to improve the quality and clarity of APIs.