I am creating API by Swagger 2.0. Everything is good on Swagger 2.0, but, when build it to Slate, all the example value is not shown, just show the data type.
Ex. In swagger, what I want is:
{
"cd": 0,
"data": {
"Num1": "113.90083333",
"Num2": "113.5991"
}
}
But in Slate interface after being built,
{
"cd": "string",
"data": {
"Num1": "number",
"Num2": "number"
}
}
YAML code:
/mar:
get:
tags:
- MP
operationId: "MP1"
produces:
- application/json
responses:
200:
description: "WELL"
schema:
type: object
properties:
cd:
type: string
example: 0
data:
type: object
properties:
Num1:
type: number
example: "113.90083333"
Num2:
type: number
example: "113.5991"
Related
I'm trying to learn fastify throught the official documentation. I'm really intrested in the validation of an incoming post request with a json schema. Following the instructions i added to my routes:
fastify.addSchema({
$id: 'http://example.com/',
type: 'object',
properties: {
hello: { type: 'string' }
}
})
fastify.post('/', {
handler() { },
schema: {
body: {
type: 'array',
items: { $ref: 'http://example.com#/properties/hello' }
}
}
})
Now the problem is that I can not write a json that can be accepted by this schema. From my basic understanding a simple post request like the following should be accepted
[
{
"hello": "bye"
},
{
"hello": "bye bye"
}
]
However server keeps telling me that body[0] should be string. Where am I wrong?
The reference $ref: 'http://example.com#/properties/hello' points to the hello property schema value, which is { type: 'string' }.
This means the schema in fastify.post('/', { expects the body to be an array of strings.
So I'm extracting a JSON schema out of my RAML spec to validate output in GET methods and also the input in the POST method.
Every entity of this type has a "required" ID property - at least it's required when listing those entities in a 'get item' or 'get collection'-request.
But when validating the received post data to create such an entity the ID is obviously not required (and discarded if it's send anyway).
What's the best DRY way to have this ID property required for GET requests, but not required, or even better not existing in the type for POST requests?
TL;DR: start reading below ;)
Example to make it easier to understand:
For GET requests the type should be like:
properties:
id:
something1:
something2?:
For POST requests the type should be like:
properties:
something1:
something2?:
without having to define both separately, but also without using inheritance to have to create two types for every resource.
Ideally I would solve it that way, but that doesn't seem to work:
get:
description: Retrieve a list of <<resourcePathName|!uppercamelcase>>.
responses:
200:
body:
application/json:
type: [ entity_id_object, <<resourcePathName|!singularize|!uppercamelcase>> ][]
example: <<exampleCollection>>
and entity_id_object ist just:
entity_id_object:
properties:
id:
I think it's because the <<resourcePathName|!singularize|!uppercamelcase>> is not working in this combination.
I can't think of a way of doing it without two types yet. But this example at least only makes you only pass one type and automatically appends 'NoId' to the type name for POST requests.
#%RAML 1.0
title: My API
version: v1
mediaType: application/json
types:
ResponseNoId:
properties:
something1:
something2?:
ResponseId:
properties:
id:
something1:
something2?:
Response:
ResponseNoId|ResponseId
resourceTypes:
collection:
usage: Use this resourceType to represent a collection of items
description: A collection of <<resourcePathName|!uppercamelcase>>
get:
description: |
Get all <<resourcePathName|!uppercamelcase>>,
optionally filtered
is: [ hasResponseCollection: { typeName: <<typeName>> } ]
post:
description: |
Create a new <<resourcePathName|!uppercamelcase|!singularize>>
is: [ hasRequestItem: { typeName: <<typeName>> } ]
item:
usage: Use this resourceType to represent any single item
description: A single <<typeName>>
get:
description: Get a <<typeName>>
is: [ hasResponseItem: { typeName: <<typeName>> } ]
traits:
hasRequestItem:
body:
application/json:
type: <<typeName>>
hasResponseItem:
responses:
200:
body:
application/json:
type: <<typeName>>
hasResponseCollection:
responses:
200:
body:
application/json:
type: <<typeName>>[]
/myResource:
type: { collection: { typeName: Response } }
get:
/{id}:
type: { item: { typeName: Response } }
post:
body:
application/json:
You can mark the id field as readOnly to make the intent clear, although it won't have an effect on the way that the data is validated.
To affect validation, you can create a "Read" type and a "Write" type, where the "Read" type has the extra required id property.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"MyWriteEntity": {
"type": "object",
"properties": {
"something1": { "type": "string"},
"something2": { "type": "string"}
},
"required": "something1"
},
"MyReadEntity": {
"allOf": [
{ "$ref": "#/definitions/MyWriteEntity" },
{
"id": { "type": "string", "readOnly": true},
"required": ["id"]
}
]
}
}
}
The best way to do this is to create a RAML Library fragment, lets say "foo.raml" for a data model "foo" for resources /foos and /foos/{fooID}.
In the library, create three types:
fooInput:
properties:
something1:
something2:
fooOutput:
type: fooInput
properties:
id: integer
fooPatch:
properties:
something1?:
something2?:
Now in ONE file you have 3 data types. Use the Input version with PUT/POST, use the Output version for GET and use the Patch version for PATCH endpoints. This is even better when paired with resourceTypes.
I am designing an API operation and am going to use the expand standard.
Here is an example of my first API response....
{
"id": "000000001",
"createdDateTime": "2017-12-19T16:39:57-08:00",
"lastUpdatedDateTime": "2017-12-19T16:45:57-08:00",
"holdingDetails": {
"status": "SUCCESSFUL",
"instrument": "/api/v1//instruments/123456789"
}
}
Here is an example of my second API response....
{
"id": "000000001",
"createdDateTime": "2017-12-19T16:39:57-08:00",
"lastUpdatedDateTime": "2017-12-19T16:45:57-08:00",
"holdingDetails": {
"status": "SUCCESSFUL",
"instrument": {
"instrumentId":"123456789",
"nickName":"My NickName",
"type": "BLAH"
}
}
}
In my raml I would like to define a type for this i'm not sure what is would look like...
#%RAML 1.0 DataType
type: object
properties:
id?:
type: string
createdDateTime?:
type: datetime
lastUpdatedDateTime?:
type: datetime
What goes next? i.e. How do I say it can be either listed below
instrument?:
type: string
description: A link to the instrument
instrument?:
type: !include instrument.raml
You can use an union
e.g.:
instrument?:
type: string | InstrumentType
and of course also define InstrumentType, for example with something like this:
InstrumentType:
properties:
instrumentId:
nickName:
type:
I have created a raml in anypoint platform below is my RAML file
#%RAML 0.8
title: es-be-crm-dev
version: 001-dev
#baseUri: http://localhost:8081/api
baseUri: https://mocksvc.mulesoft.com/mocks/44267573-73b2-4369-8e2d- 3a6abbf20e34/api
traits:
- rate-limited:
queryParameters:
client_id:
type: string
client_secret:
type: string
schemas:
- api-request-schema: !include schemas/api-request-schema.json
/teams/{teamId}/teamMembers:
post:
description: Delete Team Member(s) from specified Team
headers:
Accept:
displayName: Accepted response format
description: Caller accepted response content Type
type: string
example: application/json
required: true
default: application/json
Content-Type:
displayName: body Mime Type
description: Caller accepted response content Type
type: string
example: application/json
required: true
default: application/json
body:
application/json:
schema: api-request-schema
example: !include examples/api-request-example.json
responses:
201:
description: Returned when the entity has been successfully created
headers:
ETag:
displayName: Entity Tag
description: Hash of the previously requested resource
type: string
example: asd8asd98hlk209u098asdfmoiun4023
required: false
401:
description: Returned when the user is not authorized to add a member
delete:
description: Adds Team Member(s) in specified Team
headers:
Accept:
displayName: Accepted response format
description: Caller accepted response content Type
type: string
example: application/json
required: true
default: application/json
Content-Type:
displayName: body Mime Type
description: Caller accepted response content Type
type: string
example: application/json
required: true
default: application/json
body:
application/json:
schema: api-request-schema
example: !include examples/api-request-example.json
responses:
201:
description: Returned when the entity has been successfully created
headers:
ETag:
displayName: Entity Tag
description: Hash of the previously requested resource
type: string
example: asd8asd98hlk209u098asdfmoiun4023
required: false
401:
description: Returned when the user is not authorized to delete a member
below is api-request-example.json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"teamMembers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"teamMember": {
"type": "object",
"properties": {
"empID": {
"type": "string"
},
"sourceSystemId": {
"type": "string"
},
"sourceSystemObjectId": {
"type": "string"
}
},
"required": [
"empID",
"sourceSystemId",
"sourceSystemObjectId"
]
}
},
"required": [
"teamMember"
]
}
}
},
"required": [
"teamMembers"
]
}
below is Example file
{
"teamMembers": [{
"teamMember": {
"empID": "d3193f53-5f07-e611-80e3-a45d36fc4f90",
"sourceSystemId": "abc",
"sourceSystemObjectId": "abc"
}
}]
}
whenever i try to mock my api in it throws an error with status code 400
{
"error": "schema did not parse: Unexpected token a"
}
is there anything that i am missing here ???
Has the error message says mule is not able to parse your schema and this is probably because the ApiKit version you are using does not support aliases.
That's way he says can't parse a.
Change it with a direct include
schema: !include api-request-schema.json
I know is not ideal but is just a little more to write.
We have following json response for /papers/15
{
"data": [
{
"id": 1,
"title": "foo"
},
{
"id": 2,
"title": "bar"
}
],
"meta": {
"total": 15
}
}
Does anyone know how to describe it swagger yaml file?
Ok, I just figured out how to do this, in case somebody will need id.
Beside dedicated model definitions section ("definitions") it is possible to do inline model descriptions. Code above will looks like:
responses:
"200":
description: Matched Objects
schema:
type: object
properties:
data:
type: object
properties:
authors:
type: array
items:
$ref: "#/definitions/object_with_id_and_title"