I have a definition of a report object. I have another definition of reports object that has an array of report objects (via a $ref).
In the report definition, I have an example defined, which works fine in swagger UI.
In the reports definition, I want it to use the example from the report definition.
How can I do this? I've tried several things using $ref, the closest I got was what I have in the following YAML...
definitions:
report:
type: object
properties:
ID:
type: number
format: int
description: "DB record ID of the report."
readOnly: true
ErrorContent:
type: string
description: "The actual problem or error infomation for this report. This can be exception stack, etc."
readOnly: true
UserComments:
type: string
description: "Any user comments collected by the app and submitted with the report."
readOnly: true
ReportedBy:
type: string
description: "The person using the app when it triggered the error this report is for."
readOnly: true
ReportedDateTime:
type: string
description: "The date/time the report was submitted."
readOnly: true
required:
- ID
- ErrorContent
- ErrorType
- UserComments
- ReportedBy
- ReportedDateTime
example:
ID: 11367
ErrorContent: "Operation is not valid due to the current state of the object."
ErrorType: "Exception"
UserComments: "Was clicking this and that and then Boom!"
ReportedBy: "domain\\name"
ReportedDateTime: "2016-01-19 14:07:00"
reports:
properties:
message:
type: string
reports:
type: array
items:
$ref: '#/definitions/report'
example:
message: "success"
reports:
- $ref: '#/definitions/report'
However, in Swagger UI, the above results in...
{
"message": "success",
"reports": [
{
"$ref": "#/definitions/report"
}
]
}
One interesting note, in Swagger UI, when I look at the model view, it does have all of report even with descriptions.
This behavior is correct--the examples section cannot be referenced with a JSON pointer. See the OAI Specification for what is currently supported.
If you feel this is a common use case, please open an issue on the spec repository.
Related
Hi I want to create AWS::Pinpoint::PushTemplate using cloudformation template and I am following this link: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-pinpoint-pushtemplate.html.
Type: AWS::Pinpoint::PushTemplate
Properties:
Default:
Action: OPEN_APP
Body: FirstName - {{firstName}}, LastName - {{lastName}}
Title: Title
DefaultSubstitutions:
firstName: default
lastName: default
Tags:
project: project
tashi: "Pinpoint Template"
TemplateName: template_name
I am getting type validation error for`DefaultSubstitutions: Property validation failure: [Value of property {/DefaultSubstitutions} does not match type {String}]
According to docs DefaultSubstitutions is a String.
However, in your case, you set it up as map:
DefaultSubstitutions:
firstName: default
lastName: default
Maybe have to try using it as json string:
DefaultSubstitutions: "{\"firstName"\:\"default\", \"lastName"\:\"default\"}"
In swagger's documentation using OpenApi specification, you can wrap schema in parameter to content with application/json:
parameters:
- in: query
name: filter
# Wrap 'schema' into 'content.<media-type>'
content:
application/json: # <---- media type indicates how to serialize / deserialize the parameter content
schema:
type: object
properties:
type:
type: string
color:
type: string
to send objects like this filter={"type":"t-shirt","color":"blue"}.
How to do it in swagger-php?
The swagger-editor and swagger-ui have added support for http://swagger.io/docs/specification/describing-parameters
The swagger-php library has added support too, it will be part of the 3.0.4 release.
I want to define an enum value in the query string parameter of a function in an OpenAPI specification.
Here is an example of how I specify the parameter in my OpenAPI specification (yaml):
openapi: 3.0.0
info:
description: Vends sodas
version: 1.0.0
title: VendingMachineService
paths:
/soda/{bill}:
get:
summary: Provides a soda for a provided amount of money
description: Provides a soda for a provided amount of money
operationId: getSoda
parameters:
- name: bill
in: path
description: Money (e.g. one, two, five)
required: true
schema:
$ref: "#/components/schemas/Bill"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/Result"
"404":
description: Templates for Source not found
servers:
- url: http://localhost:8080/
components:
schemas:
Bill:
type: string
enum:
- one
- two
- five
Result:
type: string
The key part of the OpenAPI spec is that I define the enum in a schema object at the bottom, type string, and refer to it in the parameters section of the function, also defining it as part of the path /{bill}
I then use openapi-generator to generate the spring server:
openapi-generator generate -i ~/vending-machine.yaml -g spring -o ~/output
I then spin up the server (importing the project into Intellij and running in a spring-boot configuration) and go to localhost:8080/ to open the Swagger UI. I try to exercise the api and get the following error:
{ "timestamp": "2019-03-29T15:43:14.737Z", "status": 400,
"error": "Bad Request", "message": "Failed to convert value of type
'java.lang.String' to required type 'org.openapitools.model.Bill';
nested exception is
org.springframework.core.convert.ConversionFailedException: Failed to
convert from type [java.lang.String] to type
[#javax.validation.constraints.NotNull
#io.swagger.annotations.ApiParam #javax.validation.Valid
#org.springframework.web.bind.annotation.RequestParam
org.openapitools.model.Bill] for value 'null'; nested exception is
java.lang.IllegalArgumentException: No enum constant
org.openapitools.model.Bill.null", "path": "/soda/%7Bbill%7D" }
(501 Not Implemented expected)
What is the proper way to define the query params & enum in the OpenAPI spec to use enum values?
I want to use AWS macro Transform::Include with some dynamic parameters for my file.
Resources:
'Fn::Transform':
Name: 'AWS::Include'
Parameters:
TestMacroVariable:
Default: 2
Type: Number
Location: !Sub "s3://${InstallBucketName}/test.yaml"
test.yaml:
DataAutoScalingGroup:
Type: AWS::AutoScaling::AutoScalingGroup
Properties:
LaunchConfigurationName:
Ref: DataLaunchConfiguration
MinSize: '1'
MaxSize: '100'
DesiredCapacity:
Ref: TestMacroVariable
...
After calling: aws cloudformation describe-stack-events --stack-name $stack
I get:
"ResourceStatusReason": "The value of parameter TestMacroVariable
under transform Include must resolve to a string, number, boolean or a
list of any of these.. Rollback requested by user."
When I try to do it this way:
Resources:
'Fn::Transform':
Name: 'AWS::Include'
Parameters:
TestMacroVariable: 2
Location: !Sub "s3://${InstallBucketName}/test.yaml"
I get:
"ResourceStatusReason": "Template format error: Unresolved resource
dependencies [TestMacroVariable] in the Resources block of the
template"
Error is the same when I don't provide TestMacroVariable at all.
Tried with different types: String, Number, Boolean, List - none of them work.
As i know you cannot have anything other than Location key in the Parameters section of the AWS::Include. Check here AWS DOC
As an alternative, you can pass in the whole S3 path as a parameter and reference it in Location:
Parameters:
MyS3Path:
Type: String
Default: 's3://my-cf-templates/my-include.yaml'
...
'Fn::Transform':
Name: 'AWS::Include'
Parameters:
Location: !Ref MyS3Path
Building on what #BatteryAcid Said you can refer the parameters in your Cloudformation template directly from your file using Sub function:
In your CF template :
Parameters:
TableName:
Type: String
Description: Table Name of the Dynamo DB Users table
Default: 'Users'
In the file you are including:
"Resource": [
{
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}",
{
"tableName": {
"Ref": "TableName"
}
}
]
}
Alternatively doesn't have to be a parameter but any resource from your template :
Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${QueryTelemtryFunction.Arn}/invocations
I'm trying to generate my API at the moment but having some difficulty adding a description for the first method within a listing group. I can add a description for every other method in a group, just not the first one.
I have attached an image below of how I want it to look but I cannot achieve this using the RAMLtoHTML generator.
Below is the code I am using in the main file. This file has an include for the file I am having the problem with. I was thinking maybe I could change something in it?
#%RAML 0.8
title: Hubs
baseUri: https://apis.3dissue.com/hubsdashboard/api/{version}
version: v1
mediaType: application/json
documentation:
- title: Getting Started
content: !include md/getting_started.md
- title: Overview
content: !include md/overview.md
- title: Creating a Hub
content: !include md/creating_hub.md
- title: Adding Social Sources to a Hub
content: !include md/social_sources.md
- title: Adding an Article to a Hub
content: !include md/articles.md
traits: !include traits.raml
#Hubs
/hubs: !include calls/hubs.raml
This is the file I want to add the description in below. As you can see, I have already added a listing description and if I try to add a method description here, then I get a complaint from the parser that "description" is already defined.
is: [appkey]
displayName: User Hubs
description: This group contains methods that will allow you to create, manage, and retrieve details of one or more hubs.
get:
description: Returns a JSON array containing details of hubs associated with the user account.
queryParameters:
page:
description: The page number to be returned within the paged results. By default, this will return the first page.
type: number
default: 1
page_size:
description: The number of elements to return per page. By default, a total of 10 elements will be returned. This parameter should be used in combination with the page parameter for setting up paged results.
type: number
default: 10
related:
description: Determines whether to return related objects. If set to 1, all child elements for each hub in the list will be returned including any sections and sources.
type: boolean
default: 0
body:
example: !include ../php/getListOfHubs.php
responses:
200:
body:
application/json:
example: !include ../json/hubs.json
post:
description: This method will allow you to create a new hub.
body:
example: !include ../php/createHub.php
responses:
200:
body:
application/json:
example: !include ../json/hub_create_response.json
/{hub_id}:
description: The following methods can be used to manage or retrieve details for a given hub.
uriParameters:
hub_id:
description: A string value used to uniquely identify a hub.
type: string
get:
description: Returns a JSON array containing details for the given hub.
body:
example: !include ../php/getHub.php
responses:
200:
body:
application/json:
example: !include ../json/hub.json
put:
description: This method will allow you to update the display name of the given hub.
body:
example: !include ../php/updateHub.php
responses:
200:
body:
application/json:
example: !include ../json/hub.json
delete:
description: This method will allow you to delete the selected hub. Deleting a hub will not remove any sources from your account.
body:
example: !include ../php/deleteHub.php
responses:
204:
description: No response body
Does anyone have a workaround for this? I have tried adding the description within the first file before the include but get parser errors. I have also tried moving the /hubs declaration within the second file but the only way I can get it to parse is by adding in an extra character to the method call URL which is far from ideal.