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
Related
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}"}
For example if i have:
paths:
\some:
post:
description: Sample request
parameters:
- in: header
name: firstHeader
schema:
type: string
How can I add this header in every request, without repeating this code? I've tried to reference as object after parameters, but in that case it won't be part of the headers of the request.
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
[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)
I have below requirement for designing simple RAML. I’m newbie in RAML coding so would like to know if my code is according to requirement or not
Requirement:
Has at least 1 endpoint with a GET and POST method.
Includes description attribute of the API
Includes description attribute of the method
The GET request takes a query parameter of "mulesoft"
Define the response with an object that contains least a string and
integer data type
Includes an example for a 200 response code that matches the
definition’s response object from above
My code:
#%RAML 1.0
title: Coding_Champions
version: 1.0.development
baseUri: http://localhost:8004/api
description: This API displays and adds Organisation with details
types:
Org:
type: object
properties:
name: string
address: string
pincode: integer
/details:
displayName: Company Details
description: Coding challenge which takes query parameter of "mulesoft"
get:
description: Retrieve a list of all the Orgs
queryParameters:
mulesoft:
description: Specify the Org name that you want to retrieve
type: boolean
required: true
responses:
200:
body:
application/json:
type: Org
examples:
MuleSoft:
name: MuleSoft
address: 77 Geary Street, Suite 400
pincode: 94108
post:
description: Add a Org to list
body:
application/json:
type: Org
examples:
Cognizant:
name: Cognizant
address: DLF
pincode: 9771
responses:
201:
body:
application/json:
example: |
{
"message":"New Org updated but not really"
}
I’m more of concerned with one of point in the requirement
"The GET request takes a query parameter of “mulesoft”
Does it mean I should give mulesoft as parameter dynamically in my url, If yes then other than mulesoft is passed as parameter then it should throw an error ?
(or)
Does it mean i need to hard code “mulesoft” in my RAML code as I have done now ?
Can you please clear me on this ?
Does it mean I need to hard code “mulesoft” in my RAML code as I have
done now ?
Yes.You should define that in RAML as you are doing right now.Since its required parameter,its presence could be validated in implementation.