Defining Array of Objects in Swagger Documentation - ruby-on-rails

I'm using swagger for quite a bit now, we have started documenting our code using it, in one place there's an API response which returns multiple objects in the included block.
Example:
{
"data": {
"id": "1",
"type": "schoolPositions",
"attributes": {
"description": "teases the students",
"mustHaves": "principle"
},
"relationships": {
"schoolLocation": {
"data": {
"id": "72",
"type": "schoolLocations"
}
},
"schoolCompensation": {
"data": {
"id": "75",
"type": "schoolCompensations"
}
},
"jobSpecs": {
"data": [
{
"id": "82",
"type": "schoolAttachments"
}
]
}
}
},
"included": [
{
"id": "72",
"type": "schoolLocations",
"attributes": {
"city": "Berhampore",
"state": "West Bengal",
"postalCode": "742101",
"country": "India",
"globalRegionId": 30,
"regionId": 683
}
},
{
"id": "75",
"type": "schoolCompensations",
"attributes": {
"salary": "",
"bonus": "",
"equity": "",
"currencyId": null,
"equityType": "percent",
"salaryDescription": null
}
},
{
"id": "82",
"type": "schoolAttachments",
"attributes": {
"attachmentType": "JobSpecificationAttachmentType",
"fileFileName": "vs.jpg",
"fileContentType": "image/jpeg",
"fileFileSize": 2410039,
"fileUpdatedAt": "2018-12-12T07:06:38Z",
"downloadUrl": "001-vs.jpg?1544598398",
"klass": "SchoolAttachments"
}
}
]
I have wasted an entire day on the internet and documentation trying to document the included part, but I'm going wrong somewhere
response 200 do
key :description, 'School Data'
schema do
property :data do
key :type, :array
items do
key :'$ref', :School
end
end
property :included do
key :type, :array
items do
key :'$ref', :SchoolLocations
key :'$ref', :SchoolCompensations
key :'$ref', :SchoolAttachments
end
end
end
end
This shows only the SchoolAttachments in the included part.
I have tried using allOff but it doesn't work.

Related

Swagger data validation with allOf and additional properties

Need help to solve a swagger definiton schema using allOf and additionalProperties: false
Here my JSON Schema
"deliveryContact": {
"allOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 1024
},
"phone": {
"type": "string",
"maxLength": 24
}
}
},
{
"$ref": "#/definitions/address"
}
]
},
"address": {
"type": "object",
"additionalProperties": false,
"properties": {
"address": {
"type": "string",
"maxLength": 1024
},
"postalCode": {
"type": "string",
"maxLength": 12
},
"city": {
"type": "string",
"maxLength": 512
},
"state": {
"type": "string",
"maxLength": 512
}
}
},
Sample data
delivery: {
address: 'my address',
postalCode: 'my postalCode',
city: 'my city',
state: 'my state',
name: 'my name',
phone: 'my phone'
},
I use AJV 6.10.0 to validate my data, but I think I have a wrong schema definition.
With Ajv options :
ajv = require('ajv')({
allErrors: true,
verbose: true,
removeAdditional: false,
});
Actually, I have 6 errors which warn of additional properties for each property
During validation of the first object in allOf (name and phone), validation found the error on (address, postalCode, city and state)
If I remove additionalProperties of the first allOf object (name, phone), during validation of address schema, the validation found the error on (name and phone)
How can I solve my schema definition
I managed to make it works, I have update your data structure to be more logical, see below :
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": [
"delivery"
],
"properties": {
"delivery": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"phone",
"address"
],
"properties": {
"name": {
"type": "string",
"maxLength": 1024
},
"phone": {
"type": "string",
"maxLength": 24
},
"address": {
"$ref": "#/definitions/address"
}
}
}
},
"definitions": {
"address": {
"type": "object",
"additionalProperties": false,
"properties": {
"address": {
"type": "string",
"maxLength": 1024
},
"postalCode": {
"type": "string",
"maxLength": 12
},
"city": {
"type": "string",
"maxLength": 512
},
"state": {
"type": "string",
"maxLength": 512
}
}
}
}
}
Sample data
{
"delivery": {
"address": {
"address": "myaddress",
"postalCode": "mypostalCode",
"city": "mycity",
"state": "mystate"
},
"name": "myname",
"phone": "myphone"
}
}
If you want to test it, you can do that here : https://www.jsonschemavalidator.net/

Creating an avro schema for an array with multiple record types?

I am creating an avro schema for a JSON payload that appear to have an array of multiple objects. I'm not sure exactly how to represent this in the schema. The key in question is content:
{
"id": "channel-id",
"name": "My Channel with a New Title",
"description": "Herpy me derpy merpus herpsum ner berp berps derp ter tee",
"privacyLevel": "<private|org>",
"planId": "some-plan-id",
"owner": "a-user-handle",
"curators": [
"user-handle-1",
"user-handle-2"
],
"members": 5,
"content": [
{
"id": "docker",
"slug": "docker",
"index": 1,
"type": "path"
},
{
"id": "such-linkage",
"slug": "such-linkage",
"index": 2,
"type": "external-link",
"details": {
"url": "http://some-dank-link.com",
"title": "My Dank Link",
"contentType": "External Link",
"level": "Beginner",
"duration": "PT34293H33M9S"
}
},
{
"id": "21f1e812-b10a-40df-8b52-3a1d05fc215c",
"slug": "windows-azure-storage-in-depth",
"index": 3,
"type": "course"
},
{
"id": "7c346c05-6416-42dd-80b2-d5e758de7926",
"slug": "7c346c05-6416-42dd-80b2-d5e758de7926",
"index": 4,
"type": "project"
}
],
"imageUrls": ["https://url/to/an/image", "https://url/to/another/image"],
"analyticsEnabled": true,
"orgDiscoverable": false,
"createdDate": "2015-12-31T01:23:45+00:00",
"archiveDate": "2015-12-31T01:23:45+00:00",
"messagePublishedAt": "2015-12-31T01:23:45+00:00"
}
If you are asking if it is possible create an array with different kind of records, it is. Avro support this through union. it would looks like .
{
"name": "myRecord",
"type":"record",
"fields":[
{
"name":"myArrayWithMultiplesTypes",
"type":{
"type": "array",
"items":[
{
"name":"typeOne",
"type":"record",
"fields":[
{"name":"name", "type":"string"}
]
},
{
"name":"typeTwo",
"type":"record",
"fields":[
{"name":"id", "type":"int"}
]
}
]
}
}
]
}
If you already have the records defined previously, then it could look like this:
{
"name": "mulitplePossibleTypes",
"type": [
"null",
{
"type": "array",
"items": [
"com.xyz.kola.cloud.events.itemmanager.Part",
"com.xyz.kola.cloud.events.itemmanager.Document",
"com.xyz.kola.cloud.events.itemmanager.DigitalModel",
"com.xyz.kola.cloud.events.itemmanager.Interface"
]
}
]
},

Swagger array of different objects

For example I need to represent following structure in swagger yaml format:
"included": [
{
"type": "people",
"id": "42",
"attributes": {
"name": "John",
"age": 80,
"gender": "male"
}
}
]
With single object everything is fine:
included:
type: "array"
items:
type: object
properties:
type:
type: "string"
# and so on
The question is what if I need to describe something like:
"included": [{
"type": "people",
"id": "9",
"attributes": {
"first-name": "Dan",
"last-name": "Gebhardt",
"twitter": "dgeb"
},
"links": {
"self": "http://example.com/people/9"
}
}, {
"type": "comments",
"id": "5",
"attributes": {
"body": "First!"
},
"relationships": {
"author": {
"data": { "type": "people", "id": "2" }
}
},
"links": {
"self": "http://example.com/comments/5"
}
}, {
"type": "comments",
"id": "12",
"attributes": {
"body": "I like XML better"
},
"relationships": {
"author": {
"data": { "type": "people", "id": "9" }
}
},
"links": {
"self": "http://example.com/comments/12"
}
}]
I know that in OpenAPI it's possible ( aka swagger 3 ) and tried some workarounds in current version but with no luck.

JSON API Resources relationship attributes

I have two models related :
class Item < ActiveRecord::Base
belongs_to :carousel
end
And
class Carousel < ActiveRecord::Base
has_many :items
end
I trying to open API to carousels using the JSON API Resources gem, i need to show carousel attributes and some items attributes, something like this:
{
"data": [
{
"id": "1",
"type": "carousels",
"links": {
"self": "http://localhost:3000/api/v1/carousels/1"
},
"attributes": {
"name": "primary",
"items": [
{
"title": "first item",
"file-url": "url",
"index": 0
},
{
"title": "second item",
"file-url": "url",
"index": 1
}
]
}
}
]
}
My carousel resource:
module Api
module V1
class CarouselResource < JSONAPI::Resource
immutable
attributes :name, :items
def self.records(options = {})
user = options[:context][:current_user]
user.carousels
end
end
end
end
My result:
{
"data": [
{
"id": "1",
"type": "carousels",
"links": {
"self": "http://localhost:3000/api/v1/carousels/1"
},
"attributes": {
"name": "primary",
"items": [
{
"id": 3,
"carousel_id": 1,
"file": {
"url": "url"
},
"title": "first item",
"kind": 0,
"index": 0,
"created_at": "2017-02-23T10:31:53.592-03:00",
"updated_at": "2017-03-01T10:30:52.533-03:00"
},
{
"id": 5,
"carousel_id": 1,
"file": {
"url": "url"
},
"title": "second item",
"kind": 0,
"index": 1,
"created_at": "2017-03-01T10:30:07.011-03:00",
"updated_at": "2017-03-01T10:30:07.011-03:00"
}
]
}
}
]
}

How do I create (or update) a QBO BillPayment so that it has an unapplied payment amount?

I created a bill through the QuickBooks Online (QBO) web UI. Then I queried using the API (v3, documented here). The response:
{
"SyncToken": "16",
"domain": "QBO",
"VendorRef": {
"name": "MyVendor",
"value": "237"
},
"TxnDate": "2014-12-07",
"TotalAmt": 1.83,
"CurrencyRef": {
"name": "United States Dollar",
"value": "USD"
},
"PayType": "Check",
"PrivateNote": "test billpayment description (mod)",
"sparse": false,
"Line": [
{
"Amount": 1.22,
"LinkedTxn": [
{
"TxnId": "1412",
"TxnType": "Bill"
}
]
}
],
"Id": "1413",
"CheckPayment": {
"PrintStatus": "NeedToPrint",
"BankAccountRef": {
"name": "MyBankAcct#1234",
"value": "137"
}
},
"MetaData": {
"CreateTime": "2014-12-07T18:44:51-08:00",
"LastUpdatedTime": "2014-12-10T20:20:28-08:00"
}
}
As you can see, it has $0.61 of the TotalAmt unapplied to any Bills. (The other $1.22 is applied to Bill 1412.) Now, when I try to update this bill to change JUST the amount applied to the linked transaction, I get unexpected results.
Here's the update request body:
{
"SyncToken": "16",
"domain": "QBO",
"VendorRef": {
"name": "MyVendor",
"value": "237"
},
"TxnDate": "2014-12-07",
"TotalAmt": 1.83,
"CurrencyRef": {
"name": "United States Dollar",
"value": "USD"
},
"PayType": "Check",
"PrivateNote": "test billpayment description (mod)",
"sparse": false,
"Line": [
{
"Amount": 1.21,
"LinkedTxn": [
{
"TxnId": "1412",
"TxnType": "Bill"
}
]
}
],
"Id": "1413",
"CheckPayment": {
"PrintStatus": "NeedToPrint",
"BankAccountRef": {
"name": "MyBankAcct#1234",
"value": "137"
}
},
"MetaData": {
"CreateTime": "2014-12-07T18:44:51-08:00",
"LastUpdatedTime": "2014-12-10T20:20:28-08:00"
}
}
In the response, it appears that the API just basically can't handle the situation (even though it clearly existed when I created it in the web UI). Look what happens to the TotalAmt attribute! It's reduced to whatever the payment was in the LinkedTxn:
{
"BillPayment": {
"VendorRef": {
"value": "237",
"name": "MyVendor"
},
"PayType": "Check",
"CheckPayment": {
"BankAccountRef": {
"value": "137",
"name": "MyBankAcct#1234"
},
"PrintStatus": "NeedToPrint"
},
"TotalAmt": 1.21,
"domain": "QBO",
"sparse": false,
"Id": "1413",
"SyncToken": "17",
"MetaData": {
"CreateTime": "2014-12-07T18:44:51-08:00",
"LastUpdatedTime": "2014-12-10T20:25:02-08:00"
},
"TxnDate": "2014-12-07",
"CurrencyRef": {
"value": "USD",
"name": "United States Dollar"
},
"PrivateNote": "test billpayment description (mod)",
"Line": [
{
"Amount": 1.21,
"LinkedTxn": [
{
"TxnId": "1412",
"TxnType": "Bill"
}
]
}
]
},
"time": "2014-12-10T20:25:01.91-08:00"
}
I don't see discussion of this on the known issues page, so I'm pretty confused.
If you have any suggestions as to how to get this to do what I want it to, I thank you for your thoughts!

Resources