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?
Related
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 have the following deinition in swagger.yaml
Content:
type: object
properties:
text:
type: string
image:
ref: "#/definitions/Image"
allowEmptyValue: true
I get Additional properties not allowed: allowEmptyValue as an error
How do I make image optional? ie might only be text no images
allowEmptyValue applies only to query parameters and means a different thing -
the parameter is included, but its value may be empty, as in ?param=.
In schemas, all properties are optional by default. You can make certain properties required by including them in the required array. Properties not listed in required are considered optional.
Content:
type: object
properties:
text:
type: string
image:
ref: "#/definitions/Image"
# text is required, image is optional
required:
- text
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
Given the following schema definition (which is a valid way to define required properties):
MySchema:
type: object
required: [property1, property2, property3]
properties:
property1:
type: integer
property2:
type: integer
property3:
type: integer
Is there a way to specify that all the properties are required?
Clarification: I'm looking for a way to say that all the properties are required, without specifying it one by one.
To be even more explicit: this does not answer my question.
That's the correct way to define model properties as required and I'm not aware of any other way to specify that all the properties are required.
For parameters, the required attribute is a boolean (true/false) instead of a list of required parameter's name. e.g.
name: avatar
in: formData
description: The avatar of the user
required: true
type: file