I don&#x27;t think anyone is arguing that machine readable specs should take the place of human readable documentation. Specs are helpful for testing, integrations, and <i>generating</i> HTML docs.<p>I agree the API provider&#x27;s primary concern should be Developer Experience, and understand why creating a spec often takes a back seat. But I suspect that soon it will be seen as critical for any production grade API to have a machine readable spec.<p>I view specs as analogous to unit tests - it doesn&#x27;t get you closer to a deliverable product, but it makes the development lifecycle <i>much</i> less painful.