Should I make a new language? I'm thinking about a subset of Javascript to write HTTP APIs documentation

I gave a spin on API blueprint some days ago and started a research on alternatives and other ways to make a clear documentation of a given RESTful API. I found out that API Blueprint has a lot of problems, such as inability to deal with multiple responses for the same request/route.

So, I'm thinking about a subset of ECMAScript language, specifically the tokens and expressions that allow JSON parsing and object/array literals. Some parts of JS would be change, though, with the addition of new semantics for tokens that exist in the language.

This is what it would look like:

+ EntityName (EntityAttribute*)
    EntityBody

A endpoint would look like this:

+ Model email
    /.+@.+\..+/

+ Model User
    {
        "name": String,
        "emails": [<email>]
    }

+ Route /user/:id
+ Request GET
+ Response 200 (application/json)
    <User>

+ Request POST (application/json)
+ Response 201

I'm also thinking about tooling: after parsing, I'd generate a set of documents that describe this API, and I could handle it to a documentation generator, an automated API testing tool, and so on. And I'll write the parser in Javascript, probably using esprima as a reference.

I'm still trying to figure out how and what do to. Is there a better way to do it? A new "language" for the matter would be too much?

References:

• https://apiblueprint.org/


• http://mongoosejs.com/docs/guide.html