I have been given the attached RAML file to use in Mule but I am having problems working out how to clean up the errors in the file and not even sure this raml file conforms to standards. The errors I am getting are for missing {} and another is missing block entry when I remove the version. Can't figure out how to resolve them.
Below is a cut down version of the RAML:
#%RAML 0.8
---
title: Databox
version: v1
protocols: [HTTPS]
baseUri: https://databox/v1/{version}
mediaType: application/json
traits:
- http-data: !include http-data.raml
resourceTypes: !include types.raml
documentation:
- title: Home
content: |
Databox 1st draft
/stores:
type:
store:
description: Stores
dataSchema: !include stores.json
The traits (http-data.raml):
responses:
200:
description: |
Success
The resourceType (types.raml):
- store:
head:
description: Retrieve data for <<description>>.
is: [ http-data ]
get:
description: Retrieve data for <<description>>.
responses:
200:
body:
application/json:
schema: |
{
"type": "object",
"properties": {
"meta": {
"title": "Data",
"type": "object",
"properties": {
"createdOn": {
"type": "string",
"format": "date-time"
}
},
"required": [
"createdOn"
]
},
"data": {
"type": "array",
"items": <<dataSchema>>
}
},
"required": [
"data"
]
}
description: |
Success. Returns a JSON object containing all <<description>>.
The schema (stores.json):
{
"id": "http://localhost:8000/stores.json#",
"$schema": "http://json-schema.org/draft-04/schema",
"title": "Databox Store Schema",
"type": "object",
"properties": {
"storeId": {
"type": "string"
},
"storeDescription": {
"type": "string"
},
},
"required": [
"storeId"
],
"additionalProperties": false
}
Thanks
RAML is valid except for that <<dataSchema>> parameter used in the json schema, not sure if that's a valid use of parameters.
I would start by replacing that <<dataSchema>> for the json in stores.json and try again.
Let me know if that works or what errors you get.
UPDATE:
Mulesoft's anypoint portal validates your RAML with just that single change, you can see it here
Related
I want to set up the conditional validation in my schema. I saw an example here on SO.
I have a similar setup, where I would like to validate if the field public is set to string "public". If it is set to "public" then I want to make fields description, attachmentUrl and tags required. If the field is not set to "public" then this fields are not required.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Update todo",
"type": "object",
"properties": {
"public": {
"type": "string"
},
"description": {
"type": "string",
"minLength": 3
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true,
"minItems": 1
},
"attachmentUrl": {
"type": "string"
}
},
"anyOf": [
{
"not": {
"properties": {
"public": { "const": "public" }
},
"required": ["public"]
}
},
{ "required": ["description", "tags", "attachmentUrl"] }
],
"additionalProperties": false
}
But, when I try to deploy it like that, I get the following error:
Invalid model specified: Validation Result: warnings : [], errors :
[Invalid model schema specified. Unsupported keyword(s): ["const"]]
The "const" keyword wasn't added until draft 06. You should upgrade to an implementation that supports at least that version.
https://json-schema.org/draft-06/json-schema-release-notes.html#additions-and-backwards-compatible-changes
Otherwise, you can use "enum" with a single value: "enum": ["public"]
I am working on Zoho API. Using postman I want to create/issue a bug in the system. For this, I am looking into Zoho Bug API. For creating a bug below are the request parameters list in the link.
Create a Bug
POST /portal/[PORTALID]/projects/[PROJECTID]/bugs/
Creates a bug.
Request Parameters
title* String Name of the bug.
description String Description of the bug.
assignee Long Assignee for the bug.
flag String Bug flag must be Internal or External.
classification_id Long Classification ID of the project.
milestone_id Long Milestone ID of the project.
due_date String [MM-DD-YYYY] Due date of the bug.
module_id Long Module ID of the project.
severity_id Long Severity ID of the project.
reproducible_id Long Reproducible ID of the project.
affectedmile_id Long Milestone ID of the project.
bug_followers Long Follower ID of the user.
uploaddoc File The maximum size to upload a file is 128 MB.
Custom Fields
CHAR1 - CHAR12 String Any text type of custom fields with string or picklist values.
LONG1 - LONG4 Long Numeric type of custom field.
DATE1 - DATE4 String [MM -DD-YYYY] Bug custom field in date format.
Sample Response
Status: 201 Created
Content Type: application/json;charset=utf-8
{
"bugs": [{
"id": 170876000001851001,
"key": "543",
"project": {
"id": 170876000000147021
},
"flag": "Internal",
"title": "UI issue in Status text box",
"reporter_id": "2060758",
"reported_person": "Patricia Boyle",
"created_time": "05-27-2014 08:38 AM",
"created_time_long": 1401188920000,
"assignee_name": "Not Assigned",
"classification": {
"id": 170876000000133041,
"type": "Feature(New)"
},
"severity": {
"id": 170876000000065005,
"type": "Major"
},
"status": {
"id": 170876000001077429,
"type": "known limitation"
},
"closed": false,
"reproducible": {
"id": 170876000000133005,
"type": "Always"
},
"module": {
"id": 170876000000494013,
"name": "ERP Phase I"
},
"link": {
"self": {
"url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/
170876000000147021/bugs/170876000001851001/"
},
"timesheet": {
"url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/
170876000000147021/bugs/170876000001851001/logs/"
}
}
}]
}
What I am doing
My request param
https://projectsapi.zoho.com/restapi/portal/[PORTALID]/projects/[PROJECTID]/bugs/
Key
`Authorization: myKey`
`Content Type: application/json`
In body
[{
"title": "My First Bug",
"description" :"This is my first bug",
"assignee" : "engr.usman" ,
"flag": "internal",
"classification_id": "1139168000000297069",
"milestone_id": "",
"due_date": "02-15-2018",
"module_id" : "1139168000000019372",
"severity_id" : "1139168000000007003",
"reproducible_id" : "1139168000000017069",
"status_id" :"1139168000000007045",
"resolution": "",
"affectedmile_id" : "",
"customfields": [
{
"column_name": "LONG1",
"label_name": "MSN#",
"value": "2999000190"
},
{
"column_name": "CHAR1",
"label_name": "Circle-Division-SubDivision",
"value": "Hyderabad - Latifabad - Tando Jam"
},
{
"column_name": "CHAR3",
"label_name": "LCD Indication",
"value": "S7"
},
{
"column_name": "CHAR2",
"label_name": "Reference #",
"value": "28371430034961U"
}
],
"uploaddoc" : [""]
}]
Response
{
"error": {
"code": 6831,
"message": "Input Parameter Missing"
}
}
Update 1
So just for testing it again. I have tried to send only mandatory and by default fields.
[{
"title": "My First Bug",
"flag": "internal",
"classification_id": "1139168000000297069",
"module_id" : "1139168000000019372",
"severity_id" : "1139168000000007003",
"customfields": [
{
"column_name": "CHAR2",
"label_name": "Reference #",
"value": "28371430034961U"
}
]
}]
But again I am getting same error Input Parameter Missing
I don't know why this error is generating. As there is no method of sending a request in the link.
Any help would be highly appreciated.
Consider an API with an endpoint in which you pass a parameter foo as part of the URL-path, and pass some parameters as json in the body of a POST request.
This uri parameter foo must have one of the values fooBar and fooBaz. Otherwise the request gest a 404.
If the value of foo is fooBar then the body attribute bar is required.
If the value of foo is fooBaz then the body attribute baz is required.
How do I specify a jsonSchema for such an endpoint?
An example for such a request would be:
POST /path/to/endpoint/fooBar HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 20
{"bar":"something"}
So far I came up with the following based on this and that but I have no idea if this is correct.
{
"$schema": "http://json-schema.org/draft-03/schema#",
"id": "http://json-schema.org/draft-03/schema#",
"definitions": {
"foo": { "enum": ["fooBar", "fooBaz"] }
},
"type": "object",
"properties": {
"foo": { "$ref": "#/definitions/foo" },
"bar": { "type": "string" },
"baz": { "type": "string" }
},
"links": [{
"rel": "self",
"href": "/path/to/endpoint/{foo}",
"hrefSchema": {
"properties": {
"foo": {"$ref": "#/definitions/foo"}
}
}
}],
"anyOf": [
{
"properties": {
"foo": { "enum": ["fooBar"] }
},
"required": ["bar"]
},
{
"properties": {
"foo": { "enum": ["fooBaz"] }
},
"required": ["baz"]
},
]
}
JSON Schema validation is not aware of the URI that the data being validated came from (if any). You can use JSON Hyper-Schema to tell your users how to send that data in the way you expect, but you will still need to do an additional check on the server-side to validate that the request was sent properly.
Before I get into the solution, I want to point out a couple things. Your $schema is set to "draft-03". If you really need "draft-03", this solution won't work. anyOf, allOf and the array form of required were added in "draft-04". hrefSchema was added in "draft-06". Since "draft-06" is brand new and is not well supported yet and you don't need hrefSchema anyway, I'm going to assume "draft-04" ("draft-05" was effectively skipped).
The next thing to mention is that you are using id wrong. It should be the identifier for your schema. You usually don't need this, but if you do, it should be the full URI identifying your schema. That is how my solution uses it.
Last thing before I get into the solution. If you are using the link keyword, you are using JSON Hyper-Schema and your $schema should reflect that. It should have "hyper-schema" instead of "schema" at the end of the URI.
Now the solution. I broke it into two parts, the schema that you put through the validator and the hyper-schema that tells users how to make the request. You've got the first one right. I only fixed the $schema and id.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "http://example.com/schema/my-foo-schema",
"type": "object",
"properties": {
"foo": { "enum": ["fooBar", "fooBaz"] },
"bar": { "type": "string" },
"baz": { "type": "string" }
},
"anyOf": [
{
"properties": {
"foo": { "enum": ["fooBar"] }
},
"required": ["bar"]
},
{
"properties": {
"foo": { "enum": ["fooBaz"] }
},
"required": ["baz"]
}
]
}
Next is the hyper-schema. You can't reference anything external (href, instance data) in a request schema, but you can write your schema so that it matches your href. The duplication is unfortunate, but that's the way you have to do it.
{
"$schema": "http://json-schema.org/draft-04/hyper-schema#",
"links": [
{
"rel": "http://example.com/rel/my-foo-relation",
"href": "/path/to/endpoint/fooBar",
"method": "POST",
"schema": {
"allOf": [{ "$ref": "http://example.com/schema/my-foo-schema" }],
"properties": {
"foo": { "enum": ["fooBar"] }
}
}
},
{
"rel": "http://example.com/rel/my-foo-relation",
"href": "/path/to/endpoint/fooBaz",
"method": "POST",
"schema": {
"allOf": [{ "$ref": "http://example.com/schema/my-foo-schema" }],
"properties": {
"foo": { "enum": ["fooBaz"] }
}
}
},
{
"rel": "self",
"href": "/path/to/endpoint"
}
]
}
Usually when I come across something that is difficult to model with hyper-schema, it means that I am doing something overly complicated with my API and I need to refactor. I suggest taking a few minutes to think about alternative designs where this switching on an enum isn't necessary.
I am fairly new to drop wizard (dropwizard.io) & just completed their tutorial. I would like to integrate Swagger (swagger.io) into this sample app.
I found:
github.com/federecio/dropwizard-swagger-sample-app
github.com/federecio/dropwizard-swagger
The generated JSON seems to be quite similar, however I cannot expand the REST resources to see their respective operations.
The only difference I noted was that the example code of the swagger integration uses SERVER whereas the official drop wizard example is using APPLICATION
Here an Image (i.stack.imgur.com/QzhPa.png)
Please could you tell me what is wrong in my approach.
Thank you very much. Here is the code to my approach: https://github.com/geoHeil/dropwizardSwaggerIntegrationNotWorking
Edit:
for api - docs {
"apiVersion": "0.0",
"swaggerVersion": "1.2",
"apis": [{
"path": "/sample"
}, {
"path": "/hello-world",
"description": "Operations about greetings"
}]
}
for sample {
"apiVersion": "0.0",
"swaggerVersion": "1.2",
"basePath": "http://geoHeil.local:8080",
"resourcePath": "/sample",
"apis": [{
"path": "/sample",
"operations": [{
"method": "GET",
"summary": "Sample endpoint",
"notes": "",
"type": "void",
"nickname": "get",
"authorizations": {},
"parameters": []
}]
}, {
"path": "/sample/hello-with-path-param/{name}",
"operations": [{
"method": "GET",
"summary": "Sample endpoint with path param",
"notes": "",
"type": "void",
"nickname": "getWithPathParam",
"authorizations": {},
"parameters": [{
"name": "name",
"required": true,
"type": "string",
"paramType": "path"
}]
}]
}, {
"path": "/sample/hello-with-query-param",
"operations": [{
"method": "GET",
"summary": "Sample endpoint with query param",
"notes": "",
"type": "void",
"nickname": "getWithQueryParam",
"authorizations": {},
"parameters": [{
"name": "name",
"required": false,
"type": "string",
"paramType": "query"
}]
}]
}]
}
for hello - world {
"apiVersion": "0.0",
"swaggerVersion": "1.2",
"basePath": "http://geoHeil.local:8080",
"resourcePath": "/hello-world",
"apis": [{
"path": "/hello-world",
"operations": [{
"method": "GET",
"summary": "Greetings endpoint",
"notes": "",
"type": "void",
"nickname": "sayHello",
"authorizations": {},
"parameters": [{
"name": "name",
"required": false,
"items": {
"type": "string"
},
"paramType": "query"
}]
}]
}]
}
There is now a Swagger spec 2.0 example available:
https://github.com/swagger-api/swagger-samples/tree/master/java/java-dropwizard
This uses the latest swagger core libraries with minimal dependencies. Note, the version of Jackson needed to be updated from dropwizard's 2.3.2 to swagger's 2.4.2.
I don't see anything obvious in the generated JSON that would cause the operations to not expand.
However, the swagger-ui bundled with the dropwizard-swagger package is a bit old. I would try using the newer version of swagger-ui.
I'm not sure if it would conflict with the bundled swagger-ui or not, but basically you need to clone https://github.com/swagger-api/swagger-ui and copy the /dist directory to your static content.
Another option is to run the swagger-ui locally (just for testing purposes) but opening the /dist/index.html and pointing it at your /api-docs directory. However, in order for that to work properly, you'd need to enable CORS - https://github.com/swagger-api/swagger-ui#cors-support.
EDIT:
I didn't notice you edited the question with the JSON, and it made it easier to read.
There's a problem with the GET /hello-world operation. It looks like it's supposed to accept an array of strings as a query parameter, but the parameter is missing a "type": "array" in its definition. I can't say what may be causing it without seeing the method's declaration and its annotations, but that's what you should be looking at.
Is there a way to have the API Kit Router validate incoming schema? I have the following in my RAML file but it does not validate the incoming schema.
- emails: |
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type" : "object",
"properties" : {
"email" : {
"type" : "string"
},
"name" : {
"type" : "string"
},
"emailOrigin" : {
"type" : "string"
}
}
}
resourceTypes:
- postbase:
post:
responses:
200:
body:
application/json:
500:
body:
application/json:
- putBase:
put:
responses:
200:
body:
application/json:
500:
body:
application/json:
/emails:
type: postbase
post:
description: |
Recieve emails captured from various parts of the site.
body:
schema: emails
The following references help you further
http://forums.raml.org/t/examples-validations-in-raml-parsers/80
Further Example as below: employeeDetailsSchema.json
{
"type": "object",
"$schema": "http://json-schema.org/draft-03/schema",
"id": "http://jsonschema.net",
"required": true,
"properties": {
"employeeID": {
"type": "string", -------> Validates the Data type
"required": true -------> Validates whether data is present or not
},
"employeeFirstName": {
"type": "string",
"required": true
},
"employeeLastName": {
"type": "string",
"required": true
},
"employeeDOB": {
"type": "string",
"required": true
}
}
}
Schema file used in my RAML
#%RAML 0.8
title: ManageEmployees
version: 1.0
baseUri: http://api.acme.com/
mediaType: application/json
/newEmployee:
post:
description: Create new employees
body:
schema: !include com/ww/schema/employeeDetailsSchema.json
put:
description: Update employees details
body:
schema: !include com/ww/schema/employeeDetailsSchema.json
responses:
200:
body:
example: !include com/ww/schema/employeeExample.json
As far as I can see, any body will be valid for that schema.
All the fields are string, not required, not any specific format.
Try putting some of the fields as required and see what happens
Cheers!