What is the use of ! in !include and ? in get?: and <<>> and also resourceTypes?
I am not able to understand with examples provided either in the official website or some other websites?
Can some explain with a clear example?
There's no use for "!" alone, the keyword "!include" includes the "!". I think the reason is to allow the use of the "include" word as a resource or in other parts of a RAML spec, without colliding with this keyword.
"?" marks the property as optional, a "get?" declares that method as optional in a resource type. "For example, a resource type declaration describes a body parameter that is used if the API defines a post method for that resource. Applying the resource type to a resource without a post method does not create the post method."
"<<>>" Double angle brackets enclose a parameter name in resource type and trait definitions. For example:
resourceTypes:
rt:
get:
description: <<someParam>>
/foo:
type: { rt: { someParam: bar } }
That, will set a get method in resource "/foo", with the description "bar"
These can be used with any name, but there are 2 reserved keywords that are useful when defining resource types and traits, which are resourcePath and resourcePathName. resourcePath is the full resource URI relative to the baseUri if there is one. And resourcePathName is the rightmost of the non-URI-parameter-containing path fragments.
For example for a resource "/groups/{groupId}", resourcePath will be exactly that and resourcePathName will be "groups". See the example bellow on how to use this.
Resource and method declarations are frequently repetitive, a Resource Type is a way of avoiding this repetition. If you have the same pattern for a group of resources, then you define a resource type "foo" and then declare the type of those resources as "foo".
In this example there are several resources which have a get method that retrieves all records of a type, and a post method that adds one of more records of a type:
types:
books: !include types/books.raml
persons: !include types/users.raml
animals: !include types/animals.raml
resourceTypes:
collection:
get:
description: get all <<resourcePathName>>
responses:
200:
body:
application/json:
type: <<resourcePathName>>
post:
description: adds one or more <<resourcePathName>>
body:
application/json:
type: <<resourcePathName>>
/books:
type: collection
/persons:
type: collection
/animals:
type: collection
The key here is using <<resourcePathName>>, when on the /books resource, <<resourcePathName>> will return "books". And thus, will set the type of the get response and the type of the post request to books.
The same happens for the other 2 resources.
Related
I have a timezone offset header parameter in my contract:
parameters:
- $ref: "#/components/parameters/timezoneOffset"
...
timezoneOffset:
in: header
name: X-Timezone-Offset
required: true
schema:
type: integer
format: int64
When generating code with swagger codegen, the parameter in method name is called xminusTimezoneMinusOffset.
#RequestHeader(value="X-Timezone-Offset", required=true) xminusTimezoneMinusOffset: kotlin.Long
That looks pretty bad and I would like it to be generated with let's say timezoneOffset variable name. Is it possible to do so?
I have a request body for an API specification in Swagger V2.0, which looks like follows.
"/uri/path":
...
parameters:
- in: body
...
schema:
$ref: '#/definitions/StatusObject'
definitions:
StatusObject:
status:
$ref: '#/definitions/StatusEnum'
StatusEnum:
type: string
enum: ['ALPHA', 'BRAVO', 'UNKNOWN']
Now, I want StatusObject.status to have the value UNKNOWN by default, if it is not set from the client end. I tried to achieve this as follows, with no luck.
"/uri/path":
...
parameters:
- in: body
...
schema:
$ref: '#/definitions/StatusObject'
definitions:
StatusObject:
status:
$ref: '#/definitions/StatusEnum'
default: 'UNKNOWN'
StatusEnum:
type: string
enum: ['ALPHA', 'BRAVO', 'UNKNOWN']
I also have tried with '#/definitions/StatusEnum.UNKNOWN' which again didn't work. Combed through the documentation as well but couldn't find anything further. What am I missing?
Response to marked duplicate
What I am trying to achieve is to set a default value for this property status. This works when the enum is defined in line as follows.
"/uri/path":
...
parameters:
- in: body
...
schema:
$ref: '#/definitions/StatusObject'
definitions:
StatusObject:
status:
type: string
enum:
- 'ALPHA'
- 'BRAVO'
- 'UNKNOWN'
default: 'UNKNOWN'
But, this won't work for me, as I'd like to reuse the enum, which otherwise I'll have to repeat at multiple places.
Since this is just a workaround and I am not sure if I can confirm if this is an answer, I won't mark this as accepted answer. That way, I think it will be still open for someone who figured out the right way, or a better way to achieve the expectation.
Apparently, the problem is with $ref. It's already known that the siblings of $ref are ignored in OpenAPI V2.0. So, enforcing any further constraints once you use $ref won't be possible.
For my specific use case, since I want to reuse my enum definition, I used YAML Anchors as defined in V2.0 docs. Even though the enum definition is repeated in each POJO it's not that much of a headache to manage, at least for the time being. The implementation I came up is as follows.
"/uri/path":
...
parameters:
- in: body
...
schema:
$ref: '#/definitions/StatusObject'
definitions:
StatusObject:
status:
enum: *STATUS_ENUM # Referencing the anchor
default: 'UNKNOWN'
StatusEnum:
type: string
enum: &STATUS_ENUM # This is the anchor
- 'ALPHA'
- 'BRAVO'
- 'UNKNOWN'
It must also be noted that, the enum values in this case cannot be defined using array syntax (i.e. ['ALPHA', 'BRAVO', 'UNKNOWN']) as it'll break the YAML syntax rules when you try to use YAML anchors alongside that.
I am using the raml2html tool to generate html documentation for my ReST apis.
I have defined all my types in a raml file memberTypes.raml that I include in the main service.raml.
Following is a sample from the service.raml file.
#%RAML 1.0
title: update member object
uses:
memberTypes: /memberTypes.raml
types:
Member:
properties:
termsAndConditions:
type: memberTypes.TermsAndConditions[]
description: The terms and conditions that the member has accepted.
required: false
person:
type: memberTypes.Person
description: The personal details of the member.
required: true
And following is a sample for the 2 properties above in memberTypes.raml
Person:
properties:
personName:
type: NameType
description: The name of the member.
required: true
dateOfBirth:
type: DateOfBirth
required: true
TermsAndConditions:
properties:
version:
type: string
description: The version of the terms and conditions.
acceptedDate:
type: date-only
description: The date on which the corresponding terms and conditions were accepted. Format is YYYY-MM-DD, ISO-8601 Calendar date format.
Now, below is the what I get in the html
The array is shown as array of memberTypes.TermsAndConditions. The questions is how do i get rid of the memberTypes? i simply want the type to be array of TermsAndConditions.
How do I achieve this? is there a command line option to raml2html tool that will do the trick?
I don't think there is command line option to do that, since the template / theme of raml2html defines how things are shown in HTML. You can edit the default theme. If I recall correctly that is defined in item.nunjucks file.
The usual use case for that is "array of objects" or "array of strings" but there is also definitions how to show non standard type types.
I'm creating a RAML file where I would like to have 2 different queryParameters for the same GET. So
/userinfo, for example, could be accessed by either set.
/userinfo:
get:
queryParameters:
...
queryParameters:
...
Similarly, this doesn't work either:
/userinfo:
get:
queryParameters:
...
get:
queryParameters:
...
But, I get the error message below:
Error: method property already used.
What is the solution?
You cannot specify a method (get, post, etc.) twice in the same resource. Nor the "queryParameters" keyword twice in the same method.
Parameters are just put one below the other.
For example:
/userinfo:
get:
queryParameters:
one:
type: integer
required: false
example: 1
two:
type: string
required: false
example: "value"
three:
More info here
You can not Define Same Resource Twice.
/userInfo is considered as a single resource, Defining again will give you errors.
In the mean time One can add multiple queryParameters Like Below.
/userinfo:
get:
queryParameters:
id: number
name: string
type: string
Consider this excerpt from https://github.com/apiaryio/mson#example-1 ...
Example 1
A simple object structure and its associated JSON expression.
MSON
- id: 1
- name: A green door
- price: 12.50
- tags: home, green
Let's say I would like to define valid values for the name attribute. Consider a context of API testing with a tool such as Dredd. We may need to define what are the expected/valid name values in response to GET'ing this resource, or else something is probably broken and this test step should fail.
And/or, if creating/updating a resource of this type, we may need to define what name values are valid/accepted. Is this currently possible to define in MSON?
(I believe this can be done in a JSON schema, which makes me hopeful for MSON support.)
Following is an example API Blueprint resource to illustrate how this would be used...
# Thing ID [/api/thing/id]
# List Thing ID attributes [GET]
+ Response 200
+ Attributes
+ href (string)
+ make (string)
+ model (string)
+ version (string)
+ Body
{"href":"/api/thing/id","make":"BrandX","model":"SuperThingy","version":"10.1"}
In the above example, there are 3 known/accepted/valid values for the model attribute: CoolThingy, AwesomeThingy, and MLGThingy
Can we represent this resource in MSON, such that...
Apiary (or other rendered) API documentation consumers can easily know what model values to expect?
Dredd processes and passes/fails the model value in the response to a GET to this resource?
In MSON you can use enum, see the example below.
name (enum[string])
joe (default)
ben
mark