Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Status
colourYellow
titleIn Progress

Spike goals:

  • check if it is possible to define a RAML file without any endpoints just to declare traits and imports, the goal is to generate DTOs and reusable traits.
  • check if it is possible to extend or inherit JSON schemas. if not demonstrate how to include or wrap JSON schemas.

Let's assume we have following *raml* file 

Code Block
themeConfluence
titlelibrary.raml
#%RAML 1.0

title: Book Library API
version: v0.1

documentation:
  - title: Introduction
    content: Automated access to books
  - title: Licensing
    content: Please respect copyrights on our books.

types:
  book: !include bookParent.json
  bookCollection: !include bookCollection.json
  errors: !include raml-util/schemas/errors.schema

traits:
  language: !include raml-util/traits/language.raml

resourceTypes:
  collection: !include raml-util/rtypes/collection.raml
  collection-item: !include raml-util/rtypes/item-collection.raml

/books:
  description: The collection of library books
  type:
    collection:
      schemaCollection: bookCollection
      schemaItem: book
      exampleCollection: !include examples/bookCollection.sample
      exampleItem: !include examples/book.sample

The definition of the book collection looks similar to other collections used in project

Code Block
themeConfluence
titlebookCollection.json
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Collection of books",
  "properties": {
    "books": {
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "bookChild.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "required": [
    "books",
    "totalRecords"
  ]
}

Here, for the reference field I have used "bookChild.json" file, which is a child  of other json file

Code Block
themeConfluence
titlebookParent.json
{ "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "description": "A book parent", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "description": "The name of the book", "type": "string" }, "author": { "description": "The author of the book",


Info
iconfalse
  • check if it is possible to define a RAML file without any endpoints just to declare traits and imports, the goal is to generate DTOs and reusable traits

Unfortunately, it is not possible to declare RAML file without any endpoint, one endpoint with at least one method should exist.

Info
iconfalse
  • check if it is possible to extend or inherit JSON schemas. if not demonstrate how to include or wrap JSON schemas.

It is possible to extend JSON schemas. The detailed information on how to do it described below.

Let's assume we have following raml file 

Code Block
themeConfluence
titlelibrary.raml
#%RAML 1.0

title: Book Library API
version: v0.1

documentation:
  - title: Introduction
    content: Automated access to books
  - title: Licensing
    content: Please respect copyrights on our books.

types:
  book: !include bookParent.json
  bookCollection: !include bookCollection.json
  errors: !include raml-util/schemas/errors.schema

traits:
  language: !include raml-util/traits/language.raml

resourceTypes:
  collection: !include raml-util/rtypes/collection.raml
  collection-item: !include raml-util/rtypes/item-collection.raml

/books:
  description: The collection of library books
  type:
    collection:
      schemaCollection: bookCollection
      schemaItem: book
      exampleCollection: !include examples/bookCollection.sample
      exampleItem: !include examples/book.sample


The definition of the book collection looks similar to other collections used in project

Code Block
themeConfluence
titlebookCollection.json
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "
string
object",
  "description": "Collection of 
}
books",

  "
metadata
properties": {

    
"
description
books": 
"Metadata
{
about
 
creation
 
and
 
changes,
 
provided
 
by
 
the server (client should not provide)
"type": "array",
      "
type
items":
"object",
 {
        "
$ref
type": "
raml-util/schemas/metadata.schema
object",
        "
readonly
$ref": 
true
"bookChild.json"
    
}
  }
,

  
"required":
 
[ "name"
 },
    "
author" ] } Code Block
themeConfluence
titlebookChild.json
totalRecords": {
  
"$schema":
 
"http://json-schema.org/draft-04/schema#",
   "type": "
object
integer"
,

    
"description": "A book child"
}
  },
  "
additionalProperties
required": 
true,
[
    "
extends
books",
:
 
{
   "totalRecords"
  
"$ref"
]
: "bookParent
}

Here, for the reference field I have used "bookChild.json"

},

file, which is a child  of other json file


Code Block
themeConfluence
titlebookParent.json
{
  "properties$schema": {
 "http://json-schema.org/draft-04/schema#",
  "idtype": {
   "object",
  "typedescription": "stringA book parent",
    }"additionalProperties": false,
    "publisherproperties": {
 
    "descriptionid": "The publisher of the book",{
      "type": "string"
    }
 ,
}
}

The main point is to use 

Code Block"extends"
    "name": {
      "
$ref
description"
: "
<json_file>" }

and set

Code Block
"additionalProperties": true

After project build we will have following models:

Code Block
themeConfluence
titleBookParent
package org.folio.rest.jaxrs.model;

import javax.validation.Valid;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Null;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;


/**
 * A book parent
 * 
 */
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({
    "id",The name of the book",
      "type": "string"
    },
    "author": {
      "description": "The author of the book",
      "type": "string"
    },
    "metadata": {
      "namedescription",: "Metadata about creation and "author"changes, provided by the server "metadata"
})
public class BookParent {(client should not provide)",
      "type": @JsonProperty("idobject"),
    private String id;
 "$ref": "raml-util/schemas/metadata.schema",
   /**   "readonly": true
 * The name of}
the book },
    * (Required)"required": [
    "name",
*    "author"
  */
]
}



Code Block
themeConfluence
titlebookChild.json
{
  "$schema": @JsonProperty("name")
    @JsonPropertyDescription("The name of the book")
    @NotNull
    private String name;
    /**
     * The author of the book"http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A book child",
  "additionalProperties": false,
  "extends" : {
    "$ref" : "bookParent.json"
  },
  "properties": {
    "publisher": {
     * (Required)
     * "description": "The publisher of the book",
       */"type": "string"
    @JsonProperty("author")}
    @JsonPropertyDescription("The author of the book")
    @NotNull
    private String author;
    /**
     * Metadata Schema
     * <p>
     * Metadata about creation and changes to records, provided by the server (client should not provide)
     * 
     */}
}


The main point is to use 

Code Block
"extends" : {
    "$ref" : "<json_file>"
  }


After project build we will have following models:


Code Block
themeConfluence
titleBookParent
package org.folio.rest.jaxrs.model;

import javax.validation.Valid;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Null;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;


/**
 * A book parent
 * 
 */
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({
    "id",
    "name",
    "author",
    "metadata"
})
public class BookParent {

    @JsonProperty("metadataid")
    private String id;
    @JsonPropertyDescription("Metadata about creation and changes to records, provided by the server (client should not provide)")
    @Null/**
     * The name of the book
     * (Required)
     @Valid* 
   private Metadata metadata;
*/
    @JsonProperty("idname")
    @JsonPropertyDescription("The name publicof Stringthe getId(book")
 {   @NotNull
    private returnString idname;
    }/**
     * The author  @JsonProperty("id")of the book
    public void* setId(StringRequired)
id) {    * 
   this.id = id;*/
    }@JsonProperty("author")
    @JsonPropertyDescription("The publicauthor BookParentof withId(String idthe book")
{    @NotNull
    this.idprivate =String idauthor;
    /**
     return* this;Metadata Schema
   }  * <p>
  /**   * Metadata about *creation Theand namechanges ofto therecords, bookprovided by the server (client should *not (Requiredprovide)
     * 
     */
    @JsonProperty("namemetadata")
    public String getName() {
        return name;@JsonPropertyDescription("Metadata about creation and changes to records, provided by the server (client should not provide)")
    @Null
}    @Valid
 /**   private Metadata metadata;
*
The name of the book @JsonProperty("id")
    public *String getId(Required) {
     *   return id;
  */  }

    @JsonProperty("nameid")
    public void setNamesetId(String nameid) {
        this.nameid = nameid;
    }

    public BookParent withNamewithId(String nameid) {
        this.nameid = nameid;
        return this;
    }

    /**
     * The authorname of the book
     * (Required)
     * 
     */
    @JsonProperty("authorname")
    public String getAuthorgetName() {
        return authorname;
    }

    /**
     * The authorname of the book
     * (Required)
     * 
     */
    @JsonProperty("authorname")
    public void setAuthorsetName(String authorname) {
        this.authorname = authorname;
    }

    public BookParent withAuthorwithName(String authorname) {
        this.authorname = authorname;
        return this;
    }

    /**
     * MetadataThe Schemaauthor of the book
  * <p>
     * Metadata about creation and changes to records, provided by the server (client should not* provide(Required)
     * 
     */
    @JsonProperty("metadataauthor")
    public MetadataString getMetadatagetAuthor() {
        return metadataauthor;
    }

    /**
     * Metadata Schema The author of the book
     * (Required)
     * 
     */
    @JsonProperty("author")
    public void * <p>
setAuthor(String author) {
    * Metadata about creation andthis.author changes= toauthor;
records, provided by the server}
(client
should not provide)  public BookParent withAuthor(String author) *{
      */  this.author   @JsonProperty("metadata")= author;
    public void setMetadata(Metadata metadata) {return this;
    }

 this.metadata = metadata; /**
   }  * Metadata Schema
 public BookParent withMetadata(Metadata metadata) {* <p>
     * Metadata this.metadataabout =creation metadata;and changes to records, provided by the server (client returnshould this;not provide)
   }  }
Code Block
titleBookChild

package org.folio.rest.jaxrs.model;

import java.util.HashMap;
import java.util.Map;
import javax.validation.Valid;
import com.fasterxml.jackson.annotation.JsonAnyGetter;
import com.fasterxml.jackson.annotation.JsonAnySetter;
import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;


/**
 * A book child
 * 
 */
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({
    "id",
    "publisher"
})
public class BookChild
    extends BookParent
{

    @JsonProperty("id")
    private String id;
    /**
     * The publisher of the book
     * 
     */
    @JsonProperty("publisher")
    @JsonPropertyDescription("The publisher of the book")
    private String publisher;
    @JsonIgnore
    @Valid
    private Map<String, Object> additionalProperties = new HashMap<String, Object>();

    @JsonProperty("id")
    public String getId() {
        return id;
    }

    @JsonProperty("id")
    public void setId(String id)* 
     */
    @JsonProperty("metadata")
    public Metadata getMetadata() {
        return metadata;
    }

    /**
     * Metadata Schema
     * <p>
     * Metadata about creation and changes to records, provided by the server (client should not provide)
     * 
     */
    @JsonProperty("metadata")
    public void setMetadata(Metadata metadata) {
        this.metadata = metadata;
    }

    public BookParent withMetadata(Metadata metadata) {
        this.metadata = metadata;
        return this;
    }

}



Code Block
titleBookChild
package org.folio.rest.jaxrs.model;

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;


/**
 * A book child
 * 
 */
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({
    "publisher"
})
public class BookChild
    extends BookParent
{

    /**
  this.id = id; * The publisher of }the book
    public BookChild* withId(String
id) {    */
    this.id = id;@JsonProperty("publisher")
    @JsonPropertyDescription("The publisher of the book")
 return this;  private String  }publisher;

    /**
     * The publisher of the book
     * 
     */
    @JsonProperty("publisher")
    public String getPublisher() {
        return publisher;
    }

    /**
     * The publisher of the book
     * 
     */
    @JsonProperty("publisher")
    public void setPublisher(String publisher) {
        this.publisher = publisher;
    }

    public BookChild withPublisher(String publisher) {
        this.publisher = publisher;
        return this;
    }

    @Override
    public BookChild withName(String name) {
        super.withName(name) = publisher;
        return this;
    }

    @Override
    public BookChild withAuthorwithId(String authorid) {
        super.withAuthorwithId(authorid);
        return this;
    }

    @Override
    public BookChild withMetadatawithName(MetadataString metadataname) {
        super.withMetadatawithName(metadataname);
        return this;
    }

    @JsonAnyGetter@Override
    public Map<String, Object> getAdditionalProperties() {
        return this.additionalProperties;
    }

    @JsonAnySetterBookChild withAuthor(String author) {
      public void setAdditionalProperty(String name, Object value) {super.withAuthor(author);
        return this;
   this.additionalProperties.put(name, value); }

   } @Override
    public BookChild withAdditionalPropertywithMetadata(String name, Object valueMetadata metadata) {
        thissuper.additionalProperties.put(name, valuewithMetadata(metadata);
        return this;
    }

}