I am trying to write an example response in Swagger UI that would depict the below JSON structure.
Ids_Match": [ {"id": "1", "value": .89}, {"id": "2", "value": .82}]
Ids_MisMatch": [ {"id": "3", "value": .56}, {"id": "4", "value": .61}]
Below is my structure but i am not able to make the response look like above
responses:
200:
description: successful operation
examples:
application/json: { "Ids_Match":{{"id":1,"value":0.89},{"id": "2", "value": .82}}}
}
400:
description: Invalid status value
Any suggestions would be appreciated.
Here is a working example:
swagger: "2.0"
info:
title: Sample API
description: API description in Markdown.
version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
- https
paths:
/find:
get:
responses:
200:
description: successful operation
examples:
application/json:
Ids_Match: [ {"id": "1", "value": .89}, {"id": "2", "value": .82}]
Ids_MisMatch: [ {"id": "3", "value": .56}, {"id": "4", "value": .61}]
It renders as following:
Related
Have below code to generate page result to get below expected result but i am getting below current result. Client using this end point is breaking as there are no items,nextpagelink and count available after upgrading the framework to net6 and odata to 8.0.11
Expected Result :
{
"items": [
{"id":6975,"name":"Dummy Value","phone":"999999999","fax":null,"address":"Dummy street","city":"Some","state":"some","zipCode":"99999","countryId":1}],
"nextPageLink":"/Vendors?$filter=zipCode%20eq%20%2785022%27&$orderby=name%20asc&$skip=50",
"count":null
}
Current Result :
{
"#odata.context": "http://localhost:8080/$metadata#Vendors",
"value":
[
{
"id": 6975,
"name": "Dummy Value",
"phone": "999999999",
"fax": null,
"address": "Dummy",
"city": "Some",
"state": "Some",
"zipCode": "99999",
"countryId": 1
}
],
"#odata.nextLink": "/Vendors?$filter=zipCode%20eq%20%2799999%27&$orderby=name%20asc&$skip=50"
Controller Code:
Start up.cs :
Expected Result :
{
"items": [
{"id":6975,"name":"Dummy Value","phone":"999999999","fax":null,"address":"Dummy street","city":"Some","state":"some","zipCode":"99999","countryId":1}],
"nextPageLink":"/Vendors?$filter=zipCode%20eq%20%2785022%27&$orderby=name%20asc&$skip=50",
"count":null
}
Current Result :
{
"#odata.context": "http://localhost:8080/$metadata#Vendors",
"value":
[
{
"id": 6975,
"name": "Dummy Value",
"phone": "999999999",
"fax": null,
"address": "Dummy",
"city": "Some",
"state": "Some",
"zipCode": "99999",
"countryId": 1
}
],
"#odata.nextLink": "/Vendors?$filter=zipCode%20eq%20%2799999%27&$orderby=name%20asc&$skip=50"
Is there any way to set up example for request body in swagger 2.0?
My scheme is the same like in https://petstore.swagger.io/
My json param:
"parameters": [
{
"in": "body",
"name": "body",
"description": "Pet object that needs to be added to the store",
"required": true,
"schema": {
"$ref": "#/definitions/Pet"
},
"x-example": "x-example": "{\r\n\"id\":123123123123123123,\r\n\"category\":{\r\n\"id\":44,\r\n\"name\":\"A12312312312312AA\"\r\n},\r\n\"name\":\"X123123123123XX\",\r\n\"photoUrls\":[\r\n\"st123123123ring\"\r\n],\r\n\"tags\":[\r\n{\r\n\"id\":0,\r\n\"name\":\"str123123ing\"\r\n}\r\n],\r\n\"status\":\"avai123123lable\"\r\n}""
}
],
I tried everything to setup my own example.
x-example:
default/(application/json):
and so on. No result.
I am using Ruby on Rails to architect a Rest API for a client and trying to document it by using SwaggerHub.
I would like to know how to document a post action with the correct parameters in the BODY. So far I have the action created and need to describe the following parameters for my developers.
{"user": {"email":"999999#gmail.com", "password":"12345678", "password_confirmation":"12345678"}}
I have started out with this for my post action:
"post": {
"description": "Creates a user",
"produces": [
"application/json"
],
"consumes": [
"application/json"
],
"responses": {
"201": {
"description": "Creates an instance of User",
},
"422": {
"description": "Bad syntax, user not created"
}
}
}
It's easy to document with the parameters " in PATH like the Get or Delete action which has the user ID in the params like this
"delete": {
"description": "Destroy a user",
"produces": [
"application/json"
],
"consumes": [
"application/json"
],
"responses": {
"200": {
"description": "destory a single user",
},
"404": {
"description": "user not found"
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of user to use for action",
"required": true,
"type": "array",
"items": {
"type": "integer"
}
How can I document the parameters with params "in": "body" ?
You just need to add a parameters list within the post and add a parameter with in set to body.
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A parameter body example
paths:
/users:
post:
description: creates a user
produces:
- application/json
consumes:
- application/json
parameters:
- name: user
in: body
schema:
properties:
user:
properties:
email:
type: string
password:
type: string
password_confirmation:
type: string
responses:
201:
description: Creates an instance of User
422:
description: Bad syntax, user not created
You can find many information about the OpenAPI (fka. Swagger) Specification by reading the specification description and this tutorial (disclosure: I wrote it).
Does anyone know how to define possible enum values in an OpenAPI 2.0 definition so that they will be displayed in the Model tab of Swagger UI? Example here has an enum option for the status property. How to do define such an enum in OpenAPI 2.0?
"enum" works like this in OpenAPI 2.0:
{
"in": "query",
"name": "sample",
"description": "a sample parameter with an enum value",
"type": "string",
"enum": [ "1", "2"],
"required": true
}
and in OpenAPI 3.0:
{
"in": "query",
"name": "sample",
"description": "a sample parameter with an enum value",
"schema": {
"type": "string",
"enum": [ "1", "2"]
},
"required": true
}
As you can see, there's a query parameter called sample of type string, and has an enum stating two possible values. In this case, the sample states the parameter is required, so the UI will not show an empty value as an option.
For a minimal working sample, try this:
{
"swagger": "2.0",
"info": {
"title": "title",
"description": "descriptor",
"version": "0.1"
},
"paths": {
"/sample": {
"post": {
"description": "sample",
"parameters": [
{
"in": "query",
"name": "sample",
"description": "a sample parameter with an enum value",
"type": "string",
"enum": [
"1",
"2"
],
"required": true
}
],
"responses": {
"200": {
"description": "Successful request."
}
}
}
}
}
}
To test it locally, you can declare a variable (for example spec) in your javascript, and pass it into the SwaggerUi object.
var spec = { ... };
window.swaggerUi = new SwaggerUi({
url: url,
spec: spec,
dom_id: "swagger-ui-container",
supportedSubmitMethods: ['get', 'post', 'put', 'delete'],
onComplete: function(swaggerApi, swaggerUi){
...
The url parameter will be ignored in this case.
Eventually, the output looks like this:
Updating this with YAML syntax.
OpenAPI 2.0:
parameters:
- in: query
name: sample
description: a sample parameter with an enum value
type: string
enum:
- 1
- 2
required: true
OpenAPI 3.0:
parameters:
- in: query
name: sample
description: a sample parameter with an enum value
schema:
type: string
enum:
- 1
- 2
required: true
This should work:
{
"name": "bookingType",
"in": "path",
"type": "array",
"items": {
"enum": [
"packages", "accommodations"
]
},
"description": "lorem ipsum"
}
Reference https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#itemsObject
This isn't the exact answer, but it might work for you until they add this functionality.
Simply declare the property like so
"MyObject":{
"properties":{
"MyEnum":{
"type":"Value1 or Value2 or Value3"
}
}
}
Your ModelSchema will show {}, but The Model will show MyEnum(Value1 or Value2 or Value3, optional)
i have a POST method REST API with request body as json, which has
{
"name": "5-Star",
"vendor": "Cadbury",
"description": "More almonds with chocolate",
"price": 5,
"primaryImage": "http://cdn.shopify.com/s/files/1/0219/2362/products/Front_a8743e5a-c6a3-4042-9cb2-834332af77d5_large.jpg?v=1377892407",
"variants":
[
{ "name" : "size",
"type" : null,
"defaultValue" : "8",
"values" :[ "8","8.5"]
},
{ "name" : "color",
"type" : "COLOR",
"values" :[ "Milky White","Chocolate"]
}
],
"tags":
[ "Chocolate", "Cadbury" ]
}
I need to know how to set parameter for variants in the above json in swagger 2.0 editor, also referenced documentation and petstore sample from swagger but i cant find any clue.
Maybe this will get you started:
properties:
... // other stuff
variants:
type: array
description: variants description
items:
properties:
name:
type: string
description: the name
... // the rest