Set body to be array of defined schema objects?


#1

Hi,

Is there a way to define a single schema object and then define the response body to be an array of that object type without defining an array schema? I am trying to avoid auto-generated code based on the RAML/JSON schemas creating a collection object. So, if I have this:

#%RAML 0.8
---
title: book
version: 1.0
mediaType: application/json
schemas:
  - book: |
      {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "book",
        "type": "object",
        "properties": {
            "isbn": {
                "description": "ISBN",
                "type": "string"
            },
            "title": {
                "description": "title",
                "type": "string"
            },
            "genre": {
                "description": "genre",
                "type": "string"
            },
            "author": {
                "$ref": "author.json"
            }
        },
        "required": [
            "title",
            "author",
            "isbn"
        ]
      }
/books:
  get:
    description: Get all books  
    responses:
      200:
        body:
            schema: syntax to return array of book items???

is there a way to update the last line to return an array?


#2

Hi, scoda,

To best I know there is no way to express it elegantly in RAML 0.8, but in RAML 1.0 you may describe it in the following way:

#%RAML 1.0
---
title: book
version: 1.0
mediaType: application/json
types:
   author: #describe author here
   book:
     properties:
      isbn:
          description: "ISBN"
          type: "string"
      title:
          description: "title"
          type: "string"
      genre?:
          description: "genre"
          type: "string"
      author:
          type: author
/books:
  get:
    description: Get all books
    responses:
      200:
        body: book[]

Regards,
Pavel


#3

Thanks.

I updated my raml to look like this:

#%RAML 1.0
---
title: book
version: 1.0
mediaType: application/json
types:
  Book: 
    type: object
    properties:
      isbn: 
        type: string
        required: true
      title: 
        type: string
        required: true
      genre: 
        type: string
      author: 
        type: Author
        required: true
  Author: 
    type: object
    properties:
      firstName: 
        type: string
        required: true
      lastName: 
        type: string
        required: true
/books:
  get:
    description: Get all books  
    responses:
      200:
        body: book[]

My ultimate goal is define an API in RAML and some way define my objects (JSON schemas, types, definitions, whatever), and then be able to auto-generate code based on those definitions. We originally had the API defined in RAML and JSON schema files defined for the objects and used RAML for JAX-RS to generate the Java classes. However, we ran into issues with the plugin only supporting RAML 0.8 and needing RAML 1.0 to use JSON schemas that referenced other JSON schemas. I have been trying to find a way to get this to work.

When I ran the RAML for JAX-RS, I get this response:

[ERROR] Failed to execute goal org.raml.plugins:raml-jaxrs-maven-plugin:1.3.4:generate (default-cli) on project BookService: Error generating Java classes from: C:\Devel\JavaProjects\BookService\src\api\BookService2.raml: Invalid RAML definition:
[ERROR] ERROR Unknown key: type (line 7, col 4 to 8)
[ERROR] ERROR Unknown key: type (line 10, col 8 to 12)
[ERROR] ERROR Unknown key: required (line 11, col 8 to 16)
[ERROR] ERROR Unknown key: isbn (line 9, col 6 to 10)
[ERROR] ERROR Unknown key: type (line 13, col 8 to 12)
... snip ....

Is there a way to define the objects such that RAML for JAX-RS can create model objects where one object is referenced in another?

I have tried writing the API in Swagger and referencing JSON schema files and using the swagger-codegen tool and it generates the models as expected. However, I prefer the cleaner way that RAML for JAX-RS defines the resource interface and other service classes.


#5

Unfortunately RAML for JAXRS does not supports RAML 1.0 yet. :frowning:

I am working on getting this support working, so if you are brave early adopter you may try using (My Branch). (any issues are very appreciated).

Regards,
Pavel


#6

Hi all,

Here /books will get you details of all the books record. What if I want response of particular record of any ‘bookId’, like: /books/{bookId} ?