raml-org / raml-spec

RAML Specification
http://raml.org
3.87k stars 859 forks source link

Add token replacement capability #139

Open justjacksonn opened 9 years ago

justjacksonn commented 9 years ago

It would be nice to have some sort of token replacement feature so as to avoid duplication of some things. For example, each of my API requests return one of several response status codes, 200, 201, 400, 401, 403, 404, 405, 500, 503, etc. For each of these, I refer to an example snippet of the response body. Each of those bodies are identical with the exception of the error code and message. I would prefer to replace this:

400:
    body:
      application/json:
        schema: errors
        example: |
          {
            "status": 400,
            "code": "E400-1",
            "message": "Bad client info",
            "more_info": "http://site.com/docs/errors/E401-1.htm"
          }

with:

400:
    body:
      application/json:
        schema: errors
        example: #errors { "status":400, "code":"E400-1", "message":"Bad client info"}

and the errors example somehow would be a template like

{ "status": "{{status}}", "code": "{{code}}", "message": "{{message}}", "more_info": "http://site.com/docs/errors/{{code}}.htm" }

I don't know the right way to refer to the template file (or inlined template) in the various places this would make sense, whatever would be best. I tend to think the {{ }} token replacement is more common than others I've seen, and possibly the way to specify the key/value pairs should be done differently too. I just think this would cut down on text and make templating an option for RAML files.

sichvoge commented 8 years ago

Are you referring to resourceTypes?