Example RAML doc that covers all aspects of the RAML spec for test purposes


#1

Hi,

I am going to attempt to build a different HTML output parser, primarily around the use of ReactJS and Bootstrap, possibly with some customizations. I can load up the RAML doc with the Java RAML module, and I think I can parse the entire contents of the doc including schemas, etc with that object. However, I am wondering if the RAML team has (or if not, can create) a good RAML doc that provides a couple of API endpoints, complete with XSD and JSON Schema refs, inlined refs, etc… basically covering the entire RAML 1.0 spec (since 1.0 is out soon), so that anyone wanting to build new parsers/converts has a good example RAML doc to work with to ensure it can handle every part of the RAML spec.

Thanks.


RAML to WADL programmatically using JAVA langauge
#2

Hi,

that sounds good. I also thought of doing something like that using docbook to create multiple formats. :slight_smile:

I will try to get something for you and send this in a PM.

Cheers,
Christian


#3

Thank you. I think it would be good to maybe pin it for others to use as a reference RAML doc. If it can cover every aspect of RAML 1.0 spec, perhaps with some of the doc tags actually explaining the bit of RAML spec it covers, would be very good.


#4

I would definitely be interested in such a document as well!


#5

I’m coming up with an example today or tomorrow :wink:


#6

Hi guys, here I have an example RAML using 1.0. The candidates you’ll see around this file are issues on github under the 1.0 milestone. You can look them up to get more information about the changes.

#%RAML 1.0
title: Example of a RAML 1.0 API
version: v1
baseUrl: http://api.example.com/{version}                # candidate #72
mediaType: application/json
types:                                                   # candidate #96
  guid:
    validationPattern: ^\w{16}$                          # candidate #97
  textDocument:
    type: file
    fileTypes: [ 'text/plain', 'text/richtext' ]         # candidate #94
    maximumLength: 1048576                               # candidate #94
  largeImage:
    type: file
    fileTypes: [ 'image/jpeg', 'image/png' ]             # candidate #94
    maximumLength: 10485760                              # candidate #94
/users:
  get:
    queryParameters:
      name:
        description: filter by name
      email:
        description: filter by email
      custom_{?}:
        description: filter by the given custom property # candidate #79
  post:
    body:
      schema:                                            # candidate #116
        type: json-schema/draft-04                       # candidate #81, #107
        definition:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
            birthday:
              type: string
              format: date-time
          required: [ name, email ]
      examples:                                          # candidate #107
        minimal:                                         # candidate #116
          name: James Bonde
          email: james.bonde@example.com
        full:                                            # candidate #116
          name: James Bonde
          email: james.bonde@example.com
          birthday: 11-11-1920
  /{userId}:
    get:
    patch:
      displayName: Update                                # candidate #74
    delete:
    /manuscripts:
      get:
      post:
        body:
          application/x-www-form-urlencoded:
            formParameters:
              contents:
                type: textDocument                       # candidate #96
              coverImage:
                type: largeImage                         # candidate #96

Hope that satisfies you guys a little bit. If you need more, tell me :slight_smile:


#7

Wow…lot of additions to the 1.0 format that I don’t quite understand yet. I assume there will be an article/forum post explaining all the new additions and how to use them at some point? When will 1.0 be released?


#8

There’s a github issues milestone that lists all of the candidates, with some explanation for each: https://github.com/raml-org/raml-spec/milestones/v1.0

I think that once we narrow down the list and make a decision on what’s in and what’s out, there will be a series of posts and examples showing how to use these. As for timing, look for it in early December – soon!