Status |
---|
colour | Yellow |
---|
title | In 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 |
---|
theme | Confluence |
---|
title | library.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 |
---|
theme | Confluence |
---|
title | bookCollection.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 |
---|
theme | Confluence |
---|
title | bookParent.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 |
---|
|
- 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 |
---|
|
- 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 |
---|
theme | Confluence |
---|
title | library.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 |
---|
theme | Confluence |
---|
title | bookCollection.json |
---|
|
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": " |
stringobject",
"description": "Collection of |
}
metadata
description"Metadataaboutcreationandchanges,providedbythe server (client should not provide)type "object",$reframl-util/schemas/metadata.schemareadonlytrue}
,"required":[
"name"author"
]
} Code Block |
---|
theme | Confluence |
---|
title | bookChild.json |
---|
|
"$schema":"http://json-schema.org/draft-04/schema#",object,"description": "A book child"additionalPropertiestrue,extends:{"$ref": "bookParentHere, for the reference field I have used "bookChild.json"
},file, which is a child of other json file
Code Block |
---|
theme | Confluence |
---|
title | bookParent.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" $ref <json_file>"
}and set
Code Block |
---|
"additionalProperties": true |
After project build we will have following models:
Code Block |
---|
theme | Confluence |
---|
title | BookParent |
---|
|
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 |
---|
theme | Confluence |
---|
title | bookChild.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 |
---|
theme | Confluence |
---|
title | BookParent |
---|
|
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 |
---|
|
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 |
---|
|
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;
}
}
|