"organizations which design systems ... are constrained to produce designs which are copies of the communication structures of these organizations" — M. Conway
RAML » Generate Clients: Yes, roughly 1 choice per language » Validate Standard: No (not in PHP anyway) » Documentation Generation: Yes, loads » Pleasant Editor: Yes Note: Weird split between version 0.8, 1.0.
API Blueprint » Generate Clients: Yes, roughly 2 generators (poor generally) » Validate Standard: Yes » Documentation Generation: Yes, 3 or 4 things » Pleasant Editor: Yes Note Blueprint was sponsored by Apiary, who have now thrown themselves behind OpenAPI Specification
Swagger is awesome but: » Don't use swaggers YAML format. » Inheritance Doesn't work well » Nulls aren't well supported (It's still pretty awesome though)
{"paths": { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "produces": [ "application/json" ], "responses": { "200": { "description": "A list of pets.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Pet" } } } } } } },