I have a problem with RAML 1.0 types. Validator gives me error on position: 0 and is_archive: false that integer and boolean are excepted. And that error occurs when i using traits.
types:
CatalogObject:
type: object
properties:
id: number
title: string
position: integer
is_archive: boolean
/catalog:
get:
responses:
200:
body:
type: CatalogObject
examples: [{
id: 1,
title: Simple1,
position: 5,
is_archive: true
}, {
id: 2,
title: Simple2,
position: 0,
is_archive: false
}]
For example:
traits:
catalogItem:
responses:
404:
description: 404 Not Found
When i removed that code, everything works fine.
The validator I use identified a few issues with the response definition. Once the errors are resolved the traits compile without an error.
body needs a mime-type
If you expect an array response, as shown in the example, the response type should be an array.
type: CatalogObject[]
The examples keyword, if choose to use that instead of example, supports multiple examples so the body should be a dictionary with a key for each example:
/catalog:
get:
responses:
200:
body:
application/json:
type: CatalogObject[]
examples:
first_example:
[{
id: 1,
title: Simple1,
position: 5,
is_archive: true
}, {
id: 2,
title: Simple2,
position: 0,
is_archive: false
}]
Related
I need to document a REST endpoint that takes the following request body:
{
"variables": [
{
"name": "groupGuid",
"value": "...",
"typeConstraint": "string",
},
{
"name": "addMembership",
"value": "...",
"typeConstraint": "boolean",
}
]
}
The variables array must take exactly 2 objects:
one with the required name groupGuid and typeConstraint string,
and the other with the required name addMembership and typeConstraint boolean.
The type of their respective values are specified by typeConstraint, but the actual values of the value properties are otherwise unconstrained.
Currently, I've got this, which is very underspecified (and possibly wrong) and relies on notes I've manually included:
'/test':
post:
requestBody:
content:
application/json:
schema:
type: object
properties:
variables:
type: array
uniqueItems: true
description: 'Must contain exactly 2 objects, with the following `name`s: (1) `groupGuid`: GUID of the group, (2) `addMembership`: Whether the task will add (true) or remove (false) members from the group.'
items:
type: object
additionalProperties: false
properties:
name:
enum:
- groupGuid
- addMembership
type: string
value:
type:
- string
- boolean
typeConstraint:
type: string
enum:
- string
- boolean
description: The type of `value`.
Is it possible to properly spec these requirements in YAML / OpenAPI 3.1.0, and if so, how? Thanks.
If what you want is to show both objects in the example body and accept either or both of them, perhaps you could use anyOf.
Below an example
paths:
/test:
post:
tags:
- Test
description: "Must contain exactly 2 objects, with the following `name`s: (1) `groupGuid`: GUID of the group, (2) `addMembership`: Whether the task will add (true) or remove (false) members from the group."
requestBody:
required: true
content:
application/json:
schema:
properties:
variables:
type: array
uniqueItems: true
items:
anyOf:
- $ref: '#/components/schemas/Object1'
- $ref: '#/components/schemas/Object2'
responses:
'200':
description: Sucess
components:
schemas:
Object1:
type: object
description: "The value here is string"
properties:
name:
type: string
value:
type: string
typeConstraint:
type: string
Object2:
type: object
description: "The value here is boolean"
properties:
name:
type: string
value:
type: string
typeConstraint:
type: boolean
openapi minimum/maximum
put:
summary: add
operationId: add
requestBody:
description: value
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Value'
components:
schemas:
Value:
type: object
required:
- value
properties:
value:
type: integer
format: int64
minimum: 1
maximum: 999
generates
#Min(1L) #Max(999L)
public Long getValue() {
return value;
}
Which is not working properly. I try
mockMvc.perform(
put(RESOURCE_URL + "/1/add")
.contentType(MediaType.APPLICATION_JSON)
.content("{\"value\":0}"))
I've no idea is it API problem or spring #Min(1L) #Max(999L) validator problem?
dependencies {
...
implementation 'org.springframework.boot:spring-boot-starter-validation'
}
I am struggling to define a request body in OpenApi. I want to force the user to send me data in the following shape:
{
"test": {
"a": "a",
"b": "b",
"abc": [
{
"type": "abc",
"name": "name"
},
{
"type": "abc",
"name": "name"
}
...more
]
}
}
This is what I tried but it does not seem to work:
schemas:
SampleRequest:
required:
- abc
properties:
abc:
$ref: "#/components/schemas/ABCType"
ABCType:
type: object
required:
- test
properties:
test:
type: array
items:
type: object
properties:
type:
type: string
name:
type: string
Any help appreciated. Thank you
With the currect json I couldn't make such sense but created this. This created a json which replicates yours.
ABCType:
type: object
additionalProperties: false
required:
- a
- b
- abc
properties:
a:
description: A of ABCType
type: string
b:
description: B of ABCType
type: string
abc:
description: Array of ABCType
type: array
items:
$ref: '#/components/schemas/ABCArrayValue'
ABCArrayValue:
type: object
additionalProperties: false
required:
- type
- name
properties:
type:
description: Type of this array value
type: string
name:
description: Name of this array value
type: string
I am quite new to Swagger, so this might be a basic question.
I am able to create .yml file for an API which takes an array of integers as parameter, as follows:
Add samples
---
tags:
- MY API
parameters:
- name: my_id
in: path
type: integer
required: true
description: Some des
- name: body
in: body
schema:
id: add_samples
required:
- sample_ids
properties:
sample_ids:
type: array
items:
type: integer
description: A list of sample ids to be added
responses:
'200':
description: Added samples.
'400':
description: Error adding samples.
This is what I send to the above API and everything works fine:
{"sample_ids": [475690,475689,475688]}
Now, instead of an array of integers, if I want to use some complex object as parameter, how to do it?
E.g. If this is what I want to send:
{"sample_ids": [{
"sample_id": "7",
"some_prop": "123"
},
{
"sample_id": "17",
"some_prop": "134"
}]}
How should the .yml file look? I have tried something like this and it doesn't seem to work:
Add sample
---
tags:
- Samples API
models:
Sample:
id: Sample
properties:
sample_id:
type: string
default: ""
description: The id for this sample
some_prop:
type: integer
description: Some prop this sample
parameters:
- name: body
in: body
schema:
id: add_sample
required:
- sample_ids
properties:
samples:
type: array
description: A list of samples to be added
items:
$ref: Sample
responses:
'201':
description: Created a new sample with the provided parameters
'400':
description: SOME ERROR CODE
This one seems to work, mostly:
Add sample
---
tags:
- Samples API
models:
Sample:
id: Sample
properties:
sample_id:
type: string
default: ""
description: The id for this sample
some_prop:
type: integer
description: Some prop this sample
parameters:
- name: body
in: body
schema:
id: add_sample
required:
- sample_ids
properties:
samples:
type: array
description: A list of samples to be added
items:
$ref: Sample
responses:
'201':
description: Created a new sample with the provided parameters
'400':
description: SOME ERROR CODE
Now only problem is, in the Swagger UI, it is not showing member variables and their default values. Rather is showing it as null:
{
"samples": [
null
]
}
I am using RAML 1.0 in the mulesoft api designer.
I would like to use types/properties to describe my api responses, and also enable the mocking service so I can run the api and get back an example response. I thought if I gave the type an example value the mocking service would be able to generate the example json response. This is my test raml
#%RAML 1.0
title: Test
baseUri: https://mocksvc.mulesoft.com/mocks/<removed>
types:
Email:
description: Email address
example: Steve#test.com
/user:
get:
responses:
200:
body:
application/json:
properties:
email: Email
When I run the api through the mocking service, I expect my response body to be this:
{
"email": "Steve#test.com"
}
but the service reports that it has no information and returns this in the body
{
"message": "RAML had no response information for application/json"
}
No, it would be a cool feature but it doesn't work that way.
You need to add the example in the response:
...
types:
Email:
description: Email address
/user:
get:
responses:
200:
body:
application/json:
properties:
email: Email
example: { "email": "Steve#test.com" }
We need to provide the example type we are expecting, check this link http://raml.org/developers/raml-200-tutorial
below just added example in response body, there we can provide multiple outcomes to.
%RAML 1.0
title: Test
baseUri: https://mocksvc.mulesoft.com/mocks/
types:
Email:
description: Email address
example: Steve#test.com
/user:
get:
responses:
200:
body:
application/json:
properties:
email: Email
example:
"email" : [
{ "email" : "Steve#test.com"}
]
Types tag in Raml 1.0 is more powerful. You have design your custom type as per comfort and also increase reputability of the code
#%RAML 1.0
title: Brochure
version: v1
baseUri: https://mocksvc.mulesoft.com/mocks/63063930-851d-41cc-b021-36d8a435d800 # baseUri: http://localhost:8080
protocols: HTTP
mediaType: application/json
types:
ModelTree:
type: object
properties:
modelTreeReference: string
brand: string
series?: string
constructionSeries?: string
bodyType?: string
AGModelCode?: string
UKModelCode?: string
levelCode?: number
Brochure:
type: object
properties:
recordNumber: number
partNumber: number
name: string
brand: string
brochureType: string
CRMGroup: string
CRMSubGroup: string
isActiveIndicator: string
modelTree: ModelTree
Status:
type: object
properties:
responseStatus:
enum: [COMPLETE, ERROR, FATAL]
responseId: number
Transaction:
type: object
properties:
status: Status
data:
type: object
properties:
brochures?: Brochure[]
/brochures:
get:
responses:
200:
description: Status and a list of Brochures
body:
application/json:
example: {
status: {
responseStatus: 'COMPLETE',
responseId: 123
},
data: {
brochures: [{
recordNumber: 1,
partNumber: 56,
name: "Activity Brochure",
brand: "My Brand Ltd",
brochureType: "HARDCOPY",
CRMGroup: "Sales",
CRMSubGroup: "Lifestyle/Access",
isActiveIndicator: "N",
modelTree: {
modelTreeReference: "My Brand",
brand: "My Brand Ltd",
levelCode: 1
}
}
]
}
}
type: Transaction
I ran into a similar issue using examples with a form encoded body. The examples given in the spec and the RAML 200 tutorial for application/json encoded responses don't work for application/x-www-form-urlencoded.
This type
types:
hub:
type: object
properties:
callback: string
mode:
enum: ["subscribe", "unsubscribe"]
topic: string
works properly with an application/json body and example
/subv1json:
post:
description: "Subscribes to a topic"
body:
application/json:
type: hub
example:
{
"callback": "http://yourcallback.url.com",
"mode": "subscribe",
"topic": "orders"
}
responses:
202:
Returns: 202 Accepted
but changing the encoding to x-www-form-urlencoded
/subv1form: #this doesn't work, returns 400 bad request
post:
description: "Subscribes to a topic"
body:
application/x-www-form-urlencoded:
type: hub
example:
{
"callback": "http://yourcallback.url.com",
"mode": "subscribe",
"topic": "orders"
}
responses:
202:
Returns 400 Bad Request and a syntax error
{
"code": "REQUEST_VALIDATION_ERROR",
"message": "Invalid schema for content type application/x-www-form-urlencoded. Errors: Syntax error in the following text: '}: { "callback": "http://yourcallback.url.com", "mode": "subscribe",'. "
}
I found that moving the example inside of the type definition didn't help - only changed the error to a more precise 'require key [mode] not found'
{
"code": "REQUEST_VALIDATION_ERROR",
"message": "Invalid schema for content type application/x-www-form-urlencoded. Errors: required key [mode] not found. "
}
However, reformatting the sample to yaml syntax does work, but requires that you do NOT specify the example in the type.
/subv3examplereformatted: #this works
post:
description: "Subscribes to a topic"
body:
application/x-www-form-urlencoded:
type: hub
example:
id: "example1"
callback: "http://yourcallback.com"
mode: "subscribe"
topic: "order"
responses:
202:
So, there is quirky-ness to how the mocking services manage serializing examples for form encoded parameters, and more than one way to provide examples. This is one work around if you want to use x-www-form-urlencoded and provide examples that work in the mocking services.