After looking at swagger (including openAPI in this), api-blueprint [1] and RAML, I've settled on api blueprint for writing documentation and even testing since

After looking at swagger (including openAPI in this), api-blueprint [1] and RAML, I've settled on api blueprint for writing documentation and even testing since it allows you to generate JSON schema from the structures you build up. It does need a touch more work to allow re-usable fragments in get arguments and a couple of other areas, but it's certainly good enough for documenting and basic testing. There's still active development from apiary as far as I can tell and the MSOn syntax is really simple to become productive with. [1] https://apiblueprint.org/ https://apiblueprint.org/