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.
Related
I have _data/navigation.yml file that looks like
main:
- title: email
url: mailto:hardcoded#email.sop
The problem is that Idk how to reuse email variable from the _config.yml in the _data/navigation.yml file.
Here is part of my _configl.yml
title: title configured
email: configured#email.sop
I've tried to adjust the _data/navigation.yml file like below
main:
- title: email
url: mailto:{{ site.email }}
but the navigation link is generated like mailto:{{%20site.email%20}}
I suppose it should be mailto:configured#email.sop as any other .md page output has.
(this is Jekyll 4.2.0 site is using the
minimal-mistake
theme)
I am using the swagger-codegen Spring generator to generate the API classes using a YAML API definition. I am describing post request with multiple parameters in the body like this:
paths:
/api/test:
post:
...
requestBody:
content:
application/json:
schema:
properties:
firstName:
type: string
lastName:
type: string
This generates a method in the ApiDelegate with the signature ResponseEntity test(Body body). However, when describing multiple post methods like this, the subsequent generated signatures have parameters of type Body1, Body2, ... . With Swagger 2.0, it was possible to name the RequestBodies. Can I do something similar with V3?
Thanks for your help!
Kind regards
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 am following Google's tutorial on setting up Google Cloud endpoint (not AWS API Gateway) in front of my Cloud Function. I am triggering my Cloud Function to trigger an AWS lambda function, AND I am trying to pass a path parameter from my Endpoint as defined by OpenAPI spec.
Path parameters are variable parts of a URL path. They are typically used to point to a specific resource within a collection, such as a user identified by ID. A URL can have several path parameters, each denoted with curly braces { }.
paths: /users/{id}:
get:
parameters:
- in: path
name: id # Note the name is the same as in the path
required: true
schema:
type: integer
GET /users/{id}
My openapi.yaml
swagger: '2.0'
info:
title: Cloud Endpoints + GCF
description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
version: 1.0.0
host: HOST
x-google-endpoints:
- name: "HOST"
allowCors: "true
schemes:
- https
produces:
- application/json
paths:
/function1/{pathParameters}:
get:
operationId: function1
parameters:
- in: path
name: pathParameters
required: true
type: string
x-google-backend:
address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/function1
responses:
'200':
description: A successful response
schema:
type: string
The error I get when I use Endpoint URL https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/function1/conversations is a TypeError from my AWS lambda function
StatusCode:200, FunctionError: "Unhandled", ExecutedVersion: "$LATEST". Payload: "errorType":"TypeError", errorMessage:"Cannot read property 'startsWith' of undefined..."
It is saying that on line
var path = event.pathParameters;
...
...
if (path.startsWith('conversations/'){...};
my path var is undefined.
I initially thought my Google Function was not correctly passing pathParameters but when I tested my Google function using triggering event {"pathParameters":"conversations"}, my Lambda returns the payload successfully.
My Google Cloud Function:
let AWS = require('aws-sdk');
AWS.config.update({
accessKeyId: 'key',
secretAccessKey: 'secret',
region: 'region'
})
let lambda = new AWS.Lambda();
exports.helloWorld = async(req,res) => {
let params = {
FunctionName:'lambdafunction',
InvocationType: "RequestRespone",
Payload: JSON.stringify(req.body)
};
res.status(200).send(await lambda.invoke(params, function(err,data){
if(err){throw err}
else{
return data.Payload
}
}).promise());
}
EDIT 1:
Seeing this Google Group post, I tried adding to my openapi.yaml file path_translation: APPEND_PATH_TO_ADDRESS, yet still I'm having no luck.
...
paths:
/{pathParameters}:
get:
...
x-google-backend:
address: https://tomy.cloudfunctions.net/function-Name
path_translation: APPEND_PATH_TO_ADDRESS
#Arunmainthan Kamalanathan mentioned in the comments that testing in AWS and Google Cloud directly with trigger event {"pathParameters":"conversations"} is not equivalent to passing req.body from my Google function to AWS lambda. I think this is where my error is occurring -- I'm not correctly passing my path parameter in the payload.
EDIT 2:
There is this Stackoverflow post concerning passing route parameters to Cloud Functions using req.path. When I console.log(req.path) I get / and console.log(req.params) I get {'0': '' }, so for some reason my path parameter is not getting passed correctly from Cloud Endpoint URL to my Google function.
I was running into the same issue when specifying multiple paths/routes within my openapi.yaml. It all depends on where you place the x-google-backend (top-level versus operation-level). This has implications on the behaviour of the path_translation. You could also overwrite path_translation yourself, as the documentation clearly describes:
path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]
Optional. Sets the path translation strategy used by ESP when making
target backend requests.
Note: When x-google-backend is used at the top level of the OpenAPI
specification, path_translation defaults to APPEND_PATH_TO_ADDRESS,
and when x-google-backend is used at the operation level of the
OpenAPI specification, path_translation defaults to CONSTANT_ADDRESS.
For more details on path translation, please see the Understanding
path translation section.
This means that if you want the path to be appended as a path parameter instead of a query parameter in your backend, you should adhere to the following scenario's:
Scenario 1: Do you have one cloud function in the x-google-backend.address that handles all of your paths in the openapi specification? Put x-google-backend at the top-level.
Scenario 2: Do you have multiple cloud functions corresponding to different paths? Put x-google-backend at the operation-level and set x-google-backend.path_translation to APPEND_PATH_TO_ADDRESS.
When your invocation type is RequestRespone, you can access the payload directly from the event parameter of lambda.
Look at the `Payload' parameter of the Google function:
let params = {
FunctionName:'lambdafunction',
InvocationType: "RequestRespone",
Payload: JSON.stringify({ name: 'Arun'})
};
res.status(200).send(await lambda.invoke(params)...)
Also the Lambda part:
exports.handler = function(event, context) {
context.succeed('Hello ' + event.name);
};
I hope this helps.
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.