API Documentation in Swagger
- name: orderNo
in: query
description: Number of the order
required: false
schema:
type: integer
format: int32
- name: orderName
in: query
description: Name of the order
required: false
schema:
type: string
JSON
"orderNo": 6362131469,
"orderName": "HuntPrivateOrder",
"lineItems": [
{
"name": "Hunt T-Shirt",
"id": 1,
"sku": 11456873613,
"quantity": 1
},
{
"name": "Hunt Tomato",
"id": 1,
"sku": 11456873677,
"quantity": 1
}
],
How do I convert my array in my JSON File to the proper Swagger Format? I only know how to convert the non-array but not the actual array. Thanks for the help!
Related
How a Json like this be documented inside response section in swagger?
{
"data": [{
"id": "",
"name": "James",
"chat": "1",
"messages": {
"current": null,
"count": null,
"length": null,
"rows": null,
"type": null
},
"cid": "204",
"cat": "messages",
"mark": false
}],
"total": 200,
"action": "success"
}
I tried
responses:
'200':
description: test data
content:
application/json:
schema:
example:
- id: null
name: James
chat: 1
messages:
current:
count:
length:
rows:
type:
cid: 204
cat: chat
mark: false
totalCount: 200
action: success
But show error bad indentation of a mapping entry
You have to define the expected object structure as a separate schema in the #/components/schemas section.
For example you name the resulting model ResponseObj, which has the properties data, total and action. The data property is another complex type with its own properties, so you also define a model for that type. This continues until you have defined all the models down to their simple property types.
Here is the definition for your example:
components:
schemas:
ResponseObj:
properties:
data:
type: array
items:
$ref: '#/components/schemas/DataObj'
total:
type: string
action:
type: string
DataObj:
properties:
id:
type: string
name:
type: string
chat:
type: string
messages:
type: array
items:
$ref: '#/components/schemas/MessageObj'
cid:
type: number
cat:
type: string
mark:
type: boolean
MessageObj:
properties:
current:
type: string
count:
type: string
length:
type: number
rows:
type: number
type:
type: string
Now you can reference the ResponseObj model as the expected result of your operation:
paths:
/example:
get:
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseObj'
I have an API that always answers with an associative array where there is only one entry with key "data" containing the final result. The result can be an object or array of objects. This is API output:
{
"data": {
"id": 1,
"name": "product1 name",
"type": "type a",
"created_at": "2011-09-28T13:20:15+02:00"
}
}
{
"data": [
{
"id": 1,
"name": "product1 name",
"type": "type a",
"created_at": "2010-09-28T13:20:15+02:00"
},
{
"id": 6,
"name": "product6 name",
"type": "type f",
"created_at": "2010-09-28T13:20:28+02:00"
},
{
"id": 17,
"name": "product17 name",
"type": "type Q",
"created_at": "2010-09-28T13:20:42+02:00"
}
]
}
How can I get swagger to show data which is the name of the key, in the docs?
As for now I only get nested array in swagger:
[
{
"id": 1,
"name": "product1 name",
"type": "type a",
"created_at": "2010-09-28T13:20:15+02:00"
}
]
[
[
{
"id": 1,
"name": "product1 name",
"type": "type_a",
"created_at": "2010-01-01T18:21:20+02:00"
}
]
]
I need the data key to be shown in swagger as it comes back from the API. Is it doable? I wasn't able to find any solution to this yet...:/
parts of my yaml file:
openapi: "3.0.0"
info:
version: 1.0.0
paths:
/products/:
get:
summary: List all available products
operationId: listProducts
tags:
- products
responses:
200:
description: Array of products
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Products"
/products/{product_id}:
get:
summary: Get specific product
operationId: showProductById
tags:
- products
parameters:
- name: product_id
in: path
required: true
description: The id of the product to retrieve
schema:
type: integer
format: int32
example: 1
responses:
200:
description: Product object
content:
application/json:
schema:
type: array
properties:
datar: string
items:
$ref: "#/components/schemas/Product"
components:
schemas:
Product:
type: object
properties:
id:
type: integer
format: int32
example: 10
name:
type: string
example: "producta name"
type:
type: string
example: "type a"
created_at:
type: string
format: date
example: "2010-01-01T18:21:20+02:00"
Products:
type: array
items:
$ref: "#/components/schemas/Product"
Any help will be much appreciated:)
Cheers
try with a "additionalProperties" in a intermediate layer for a assoc-array, source: https://swagger.io/docs/specification/data-models/dictionaries/
components:
schemas:
Product:
type: object
properties:
id:
type: integer
format: int32
example: 10
name:
type: string
example: "producta name"
type:
type: string
example: "type a"
created_at:
type: string
format: date
example: "2010-01-01T18:21:20+02:00"
ArrayOfProduct:
type: object
additionalProperties:
$ref: "#/components/schemas/Product"
Products:
type: object
properties:
data:
type: object
$ref: "#/components/schemas/ArrayOfProduct"
I am trying to implement this request:
curl -ik -X POST "https://<HOST_IP>/api/v1/roles/" -H "accept: application/json" -H "x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwidXNlcl9pZCI6IjVlMGM0Nzg0OGZiMDNhMzJmMTc0Nzc0NSIsInNvdXJjZSI6bnVsbCwicGVybWlzc2lvbnMiOnsiQUxMIjpbdHJ1ZV19LCJpYXQiOjE1Nzc4NzY0ODIsImV4cCI6MTU3NzkxOTY4Mn0.Z-WJ7ouQ5XdDqNvxMgTc-74qgW4sShtJrqTaEH-rykA" -H "Content-Type: application/json" -d "{\"users\":[{\"id\":\"5e0c47848fb03a32f1747745\",\"title\":\"admin\"}],\"groups\":null,\"permissions\":{\"ISSUES\":[\"All\"]},\"devicePermissions\":null,\"name\":\"role name\",\"description\":\"\"}"
I have this request body:
"users": [
{
"id": "5e0c47848fb03a32f1747745",
"title": "admin"
}
],
"groups": [
{
"id": "5e0c8f0d8a2c1676ed67fd2e",
"title": "asgsagas"
}
],
"permissions": {
"ISSUES": [
"All"
],
"RULES": [
"All"
]
},
"devicePermissions": null,
"name": "gasgag",
"description": ""
}
where under "permissions" object I can add (optional) additional string arrays , But I am struggling how to implement it, should I implement all options? how can I make it generic?
This is how I implemented it:
permissions:
type: object
properties:
ISSUES:
type: array
items:
type: string
example: "All"
KNOWLEDGE_EXPLORER:
type: array
items:
type: string
example: "Archive"
ANALYSIS_AND_REPORTS:
type: array
items:
type: string
example: "All"
DEVICES:
type: array
items:
type: string
example: "All"
CREDENTIALS_MANAGEMENT:
type: array
items:
type: string
example: "All"
BACKUPS:
type: array
items:
type: string
example: "All"
ABOUT:
type: array
items:
type: string
example: "All"
INTEGRATIONS:
type: array
items:
type: string
example: "All"
USERS:
type: array
items:
type: string
example: "All"
AUDIT:
type: array
items:
type: string
example: "All"
APPLICATION_SETTINGS:
type: array
items:
type: string
example: "All"
DEV_TOOLS:
type: array
items:
type: string
example: "All"
OTHER:
type: array
items:
type: string
example: "All"
I am using java in order to use this api request and I can see that maybe my implementation is not correct.
This is the expected response:
{
"ok": true,
"code": "",
"message": "Create was success",
"hasException": false,
"exception": null,
"errors": [],
"info": null,
"content": {
"devicePermissions": {
"showAll": true,
"labels": []
},
"_id": "5e0cb0ed8a2c1676ed67fd56",
"name": "devices_delete_labels_role_278932055218587",
"description": "New Role added to the system",
"permissions": {},
"updatedAt": "2020-01-01T14:47:09.792Z",
"createdAt": "2020-01-01T14:47:09.792Z",
"__v": 0
}
}
Problem: I want to reuse a definiton. Once directly and once inside an object. The following code works but the validator from http://editor.swagger.io/#/ is saying "Not a valid response definition" and pointing to the line "200".
Do I really have to define Account twice? Or is this an issue form the validator?
* responses:
* 200: <---- ERROR POINTING HERE
* description: Updated account
* schema:
* type: object
* properties:
* data:
* type: object
* properties:
* account:
* schema:
* $ref: '#/definitions/Account'
The definition itself:
"Account" : {
"type" : "object",
"required": [
"id", "username", "lastname", "firstname", "traderid", "customerid", "company", "validated"
],
"properties": {
"id": {
"type": "string"
},
"username" : {
"type": "string"
},
"lastname" : {
"type": "string"
},
"firstname" : {
"type": "string"
},
"traderid" : {
"type": "string"
},
"customerid" : {
"type": "string"
},
"company" : {
"type": "string"
},
"validated" : {
"type": "boolean"
}
},
"example" : {
"id": "57790fdde3fd3ed82681f39c",
"username": "yuhucebafu",
"validated": false,
"customerid": "57790fdce3fd3ed82681f39a"
}
},
The problem is with the use of schema in the account property.
200:
description: Updated account
schema:
type: object
properties:
data:
type: object
properties:
account:
schema: # <-- Problem is here.
$ref: '#/definitions/Account'
Here's the corrected response definition:
200:
description: Updated account
schema:
type: object
properties:
data:
type: object
properties:
account:
$ref: '#/definitions/Account'
The property name "schema" is only used as a top-level property in Swagger's response object, or a parameter object where in is set to "body".
Once you've started specifying your schema, everything within that structure mostly follows standard JSON Schema, which is highly recursive. For example:
Within an object schema, the value of each properties/[propertyName] is a schema.
Within an array schema, the value of items is a schema.
The value of each /definitions/[name] is a schema.
The value of each array element within allOf, anyOf, or oneOf is a schema.
The value of additionalProperties can be a schema (or a boolean value).
...
You get the idea. JSON Schema doesn't use the property name schema for all of these cases, because it would introduce a lot of noise in a language where practically "everything is a schema."
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