Page Comparison

Status

colour	Yellow
title	In Progress

https://issues.folio.org/browse/STCOM-447

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",
      "type": "string"
    },
    "metadata": {
      "description": "Metadata about creation and changes, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "name",
    "author"
  ]
}

Code Block

theme	Confluence
title	bookChild.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A book child",
  "additionalProperties": true,
  "extends" : {
    "$ref" : "bookParent.json"
  },
  "properties": {
    "id": {
      "type": "string"
    },
    "publisher": {
      "description": "The publisher of the book",
      "type": "string"
    }
  }
}

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("id")
    private String id;
    /**
     * The name of the book
     * (Required)
     * 
     */
    @JsonProperty("name")
    @JsonPropertyDescription("The name of the book")
    @NotNull
    private String name;
    /**
     * The author of the book
     * (Required)
     * 
     */
    @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)
     * 
     */
    @JsonProperty("metadata")
    @JsonPropertyDescription("Metadata about creation and changes to records, provided by the server (client should not provide)")
    @Null
    @Valid
    private Metadata metadata;

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

    @JsonProperty("id")
    public void setId(String id) {
        this.id = id;
    }

    public BookParent withId(String id) {
        this.id = id;
        return this;
    }

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

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

    public BookParent withName(String name) {
        this.name = name;
        return this;
    }

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

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

    public BookParent withAuthor(String author) {
        this.author = author;
        return this;
    }

    /**
     * Metadata Schema
     * <p>
     * Metadata about creation and changes to records, provided by the server (client should not provide)
     * 
     */
    @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

title	BookChild

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 Book
    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) {
        this.id = id;
    }

    public Book withId(String id) {
        this.id = id;
        return this;
    }

    /**
     * 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 Book withPublisher(String publisher) {
        this.publisher = publisher;
        return this;
    }

    @Override
    public Book withName(String name) {
        super.withName(name);
        return this;
    }

    @Override
    public Book withAuthor(String author) {
        super.withAuthor(author);
        return this;
    }

    @Override
    public Book withMetadata(Metadata metadata) {
        super.withMetadata(metadata);
        return this;
    }

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

    @JsonAnySetter
    public void setAdditionalProperty(String name, Object value) {
        this.additionalProperties.put(name, value);
    }

    public Book withAdditionalProperty(String name, Object value) {
        this.additionalProperties.put(name, value);
        return this;
    }

}

Versions Compared

Old Version 2

New Version 3

Key

Spike goals: