Second shot at the DSL draft

defineRoute02.groovy

def defineRoute(routeBuilder) {
	// defining a "categories" endpoint
	routeBuilder."/categories" {
		// defining the "Category" schema
		schema Category {
			properties {
				// this is pure jsonschema, with a builder syntax
				name { 
					type string
					description "a name" 
				}
				comments { 
					type string, 
					description "comments for this category" 
				}
				links {
					brand "brands"
				}
			}
			required ['name']
			// extending/overriding the default docs for this schema
			document { docs ->
				docs.summary = "Schema summary"
				docs
			}
		}

		// if all you need is to handle the request (standard validation, docs and auth are good)
		// then just handle it
		get { req, res ->
			// the return is not required here, but helps reading
			return [ 
				[name: "first category", comments: "first category comments"], 
				[name: "second category", comments: "second category comments"] 
			]
		}

		post { req, res ->
			// the request object will be enriched with a "data" property, containing a groovy map
			// postCategories is either a dependency or a separate method within this class
			postCategories(req.data)
		}.document { docs ->
			// overriding the standard docs for this path
			docs.summary = "Overridden summary for categories.POST"
			docs
		}
		// these commands allow a given route to bypass validation and authentication
		.skipValidation()
		.skipAuth()

		// describing a nested routs (/categories/:id)
		// the ':' syntax is based on spark
		"/:id" {
			get { req, res -> "You have reached categories/:id.get"}
			patch { req, res -> "You have reached categories/:id.patch"}
			delete { req, res -> "You have reached categories/:id.delete"}
		}
	}
}