I took a look at RAML and it also seems OK but not great like Swagger and JSON Schema. It isn't that I think I can come up with a better one, it's that I can se

I took a look at RAML and it also seems OK but not great like Swagger and JSON Schema. It isn't that I think I can come up with a better one, it's that I can see why such tools often aren't adopted and API docs are often published in non-machine-readable formats. What I didn't like was that it doesn't infer something is an object and instead you have "type:object" repeated a lot. Also properties rather than props.