I have the following endpoints configured for managing types of food
POST ~ /food/types
GET ~ /food/types
GET ~ /food/types/{id}
PUT ~ /food/types/{id}
Delete ~ /food/types/{id}
I'm trying to represent a clone operation in my REST API and wanted to avoid the use of Verbs in my endpoints.
After some research I've come up with the following as it conforms the most out of other solutions i could think of to basic REST principles:
POST ~ /food/types?sourceId={id}
This would mean that the method for this endpoint (in a typical MVC framework) would need to conditionally handle both the creation when a JSON payload is sent, and the duplication of a resource when a query parameter is provided.
I'm trying to think how i can express that in my OpenAPI specification document (v3.0.2)
Here is what i've got so far:
/api/food/types:
post:
summary: Create a new type of food
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: ./response/food-type.yaml
'400':
description: Bad Request
requestBody:
content:
application/json:
schema:
$ref: ./request/food-type.yaml
description: Create a new type of food
tags:
- Food Type
parameters: []
The request/food-type.yaml contains an object with two required parameters:
Name,
Category
When my framework validates the request against the OpenAPI specification, i want it to sometimes ignore the request body if and only if, a request parameter has been provided with a 'sourceId' parameter.
Is this type of thing even possible to express in OpenAPI 3+, or am i going about this the wrong way?
Simply put, is it possible to ignore the request body when a specific query parameter has been provided in a post request using OpenAPI 3.
And following that question, is my approach to REST lacking, and is there a better way i could represent the cloning of a resource in my API?
Use the body of the message instead to describe the source:
POST /food/types {"clone": "{id}"}
You can even use verb if you convert them into nouns:
POST /food/type-cloning {"source": "{id}"}
Related
Is it possible to add a note to the field where the Request Samples show on Swagger UI?
My API is described in the following way:
/v1/test:
post:
summary:test
tags:
- test
description: test
parameters:
- in: body
name: body
required: false
schema:
$ref: '#/definitions/test'
x-code-samples:
- lang: cURL
source: >-
When the yaml is rendered by our UI program, the Request sample is shown like this:
sample request
Is it possible to add a note someplace marked in red on the image?
I have tried adding x-description and x-summary, but that doesn't work.
I wonder if this is possible at all.
Thank you
I have the following http path devices/{sn} in a Serverless-AWS APIgateway API. The wildcard sn is a 15 digits [A-Z0-9] pattern.
In the API today any string that is not recognized as a valid path is redirected to this end-point. Ex: devices/test goes to devices/{sn}, devices/bla goes to devices/{sn} and so on. All those strings will query the database and return null because there is no such sn in the table. I could create a validation process inside the lambda to avoid the unnecessary database query. But I want to save lambda resource and I would like to validate before call the lambda.
This is what I have today for this endpoint:
- http:
path: devices/{sn}
method: GET
private: false
cors: true
authorizer: ${file(env.yml):${self:provider.stage}.authorizer}
request:
parameters:
paths:
sn: true
How can I setup this validation or filter in Serverless.yml?
In fact it should be a very straight-forward functionality of AWS/Serverless.
Let's say we have the following scenario: myPath/{id}. In this case id is a integer (a pk in a table). If I type myPath/blabla it will trigg the lambda. The system will spend resource. It shoul have a kind of previous validation - trig the endpoint only if the {id} === integer.
Your issue is very similar to this issue
According to the post and from my experience, No, I don't think you can perform validation in api-gateway level.
I am generating API documentation for our Java endpoints. I am using widdershins to convert our openAPI3.0 yaml file to markdown. Then, I am using shins to convert the markdown file to html. The request body for all of our endpoints does not appear in the generated cURL examples. Why is this? This defeats the purpose of having cURL examples because copying and pasting a cURL example without the required body will not work. Can anyone recommend a workaround or alternative tool that generates good documentation with complete cURL examples?
Example endpoint from our openAPI.yaml file...
post:
tags:
- Tools
description: Installs a tool on a user's account
operationId: Install Tool
requestBody:
description: UserTool object that needs to be installed on the user's account
content:
application/json:
schema:
$ref: '#/components/schemas/UserTool'
required: true
parameters:
responses:
default:
description: default response
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
This is the documentation our toolchain generates from this yaml file...
We would like to add a line just like the one below (grey highlight) to our cURL examples. This is a chunk from the markdown file that Widdershins produces from our openAPI yaml file. I manually added the –“d
This stack overflow Q/A suggests the answer is it is impossible to include a body parameter in a code example using swagger or openAPI. Is this correct? If so, why is this the case? What's the reasoning?
Cheers,
Gideon
I also had the same problem.
As a result of trial and error, it was found that the behavior displayed on curl varies depending on the in value.
Please look at the ParameterIn enum.
public enum ParameterIn {
DEFAULT(""),
HEADER("header"),
QUERY("query"),
PATH("path"),
COOKIE("cookie");
I tried by like below at first time:
new Parameter().name("foo").in(ParameterIn.HEADER.name())
But name return like "HEADER", So swagger(or OpenAPI) recognized to header.
It should be lower character like "header" follow ParameterIn enum.
So, you can fix it like this
new Parameter().name("foo").in(ParameterIn.HEADER.toString())
or
new Parameter().name("foo").in("header")
I also encountered the same problem and I did a little digging. It turns out I had to set options.httpSnippet option in widdershins to true so that the requestBody params will show up. However, setting that to true just shows the params if content type is of application/json. For multipart-form-data, you need to set options.experimental to true as well.
Unfortunately, there is a bug in widdershins for handling application/x-www-form-urlencoded content-type.. I created a PR for it which you can probably manually patch on the widdershins package. PR link: https://github.com/Mermade/widdershins/pull/492/files
This question already has answers here:
Can we parameterize the request file name to the Read method in Karate?
(2 answers)
Closed 1 year ago.
I want help for validating API response using karate framework.
I have API’s which are “Independent” on each other.
I have POST method along with request parameters. when I hit that particular API got the response with different parameters (no single match from request parameter and response parameter).
Now I want to validate response parameter value.
example : request: “method” post
school name: “abcd”
register date : “1:10:2010″
Response:
Principle name : ” pqrs”
Principle Email id “pqrs#gmail.com
now I want to validate that “principle name ” should not be null
I have implemented like this but it it doesn’t work
Feature: School info
Background:
* url baseUrl
Scenario: check Principles info
Given path ‘School info’
And request {school name: “abcd” ,register date : “1:10:2010”}
When method post
Then status 200
And match response.response contains {“type”: “Success”,”code”:20000}
And match response.principle list[*] { “Principle name”: “#notnull”}
whenever I run this file it always passes the API wvwnt if the Principle name filed is null.
It just checks the success message (And match response.response contains {“type”: “Success”, ”code”:20000}) and pass the API
your code for validating principlelist doesn't have proper assertions.
match each will be more convenient for validating json array with a schema
* match each response.principlelist contains {"Principal name" : "#notnull"}
[enter image description here][1]I know my syntax is wrong in the image here . But just want to let you know what I'm trying to achieve.I'm using RAML 0.8. I want to include multiple requests and responses for a single resource. Can this be achieved in RAML 0.8? Your response is much appreciated. Thank you!
You can have multiple responses in RAML 0.8, for example one for the 200 status code, one for the 404 status code, etc.
An example of this is:
/media/popular:
displayName: Most Popular Media
get:
description: |
Get a list of what media is most popular at the moment.
responses:
200:
body:
application/json:
schema: !include instagram-v1-media-popular.schema.json
503:
description: |
The service is currently unavailable or you exceeded the maximum requests
per hour allowed to your application.
body:
application/json:
schema: !include instagram-v1-meta-error.schema.json
You can specify several requests, but each for a different media type.
For example:
/jobs:
post:
description: Create a Job
body:
text/xml: !!null
application/json: !!null
You cannot have multiple examples in 0.8.
(In RAML 1 you can have multiple examples)