I'm currently documenting an API with Swagger 2.0.
The API produces application/json and application/xml.
The definition section is this:
definitions:
newsFeed:
type: object
description: the object is wrapped...
properties:
feedId:
type: string
example: '987654'
xml:
attribute: true
title:
type: string
description:
type: string
feedUrl:
type: string
example: http://heise.de.feedsportal.com/c/35207/f/653902/index.rss
logoUrl:
type: string
example: http://example.com/logo.png
language:
type: string
example: de_DE
pos:
type: string
example: '0'
active:
type: boolean
Swagger-UI generates this XML.
<?xml version="1.0" encoding="UTF-8"?>
<newsFeed feedId="987654">
<title>string</title>
<description>string</description>
<feedUrl>http://heise.de.feedsportal.com/c/35207/f/653902/index.rss</feedUrl>
<logoUrl>http://example.com/logo.png</logoUrl>
<language>de_DE</language>
<pos>0</pos>
<active>true</active>
</newsFeed>
And this JSON:
{
"feedId": "987654",
"title": "string",
"description": "string",
"feedUrl": "http://heise.de.feedsportal.com/c/35207/f/653902/index.rss",
"logoUrl": "http://example.com/logo.png",
"language": "de_DE",
"pos": "0",
"active": true
}
Both is correct, but the API deliveres a different JSON.
{
"newsFeed": {
"feedId": "987654",
"title": "string",
"description": "string",
"feedUrl": "http://heise.de.feedsportal.com/c/35207/f/653902/index.rss",
"logoUrl": "http://example.com/logo.png",
"language": "de_DE",
"pos": "0",
"active": true
}
}
How can I document this with Swagger?
Related
I am writing a openapi specification in YAML and I want to have this JSON code as a YAML file for a openAPI specification:
{
"example": [
{
"example1":
{
"type": "string"
} ,
"example2":
{
"type":"string"
}
},
{
"example1":
{
"type": "string"
},
"example2":
{
"type": "string"
},
}
]
}
I tried:
schema:
type: object
properties:
example:
type: array
items:
type: object
properties:
example1:
type: string
example2:
type: string
type: object
properties:
example1:
type: string
example2:
type: string
But you cannot have properties again because every map key has to be unique.
I am failing to to remove the outer array from the json request body that I want swagger to generate from the schema definitions.
I want to generate this object:
{
"name":
{
"value": "test04"
},
"mail": {
"value": "test04#gmail.com"
}
}
But swagger is giving me this:
[
{
"name": {
"value": "string"
},
"mail": {
"value": "string"
}
}
]
This is my definition section:
definitions:
user:
type: "object"
properties:
name:
type: object
properties:
value:
type: string
mail:
type: object
properties:
value:
type: string
May you kindly assist. I am new to swagger. I am using version 2.0
Your User schema is correct, so this means there's an extra type: array somewhere in the parameter, request body, or response where this schema is used.
I have to create an API that can return JSON object in two different formats based on the input parameter. Suppose if we pass "report=monthly" in query string the output will be like:
[{
"Month": "Jan",
"Details": [{
"userId": 12345,
"userName": "ABC"
}]
}, {
"Month": "Feb",
"Details": [{
"userId": 12346,
"userName": "ABD"
}]
}]
If the above parameter is not passed the output will be like:
{
"Details": [{
"userId": 12345,
"userName": "ABC"
}, {
"userId": 12346,
"userName": "ABD"
}]
}
How can I define schema for a single API to return JSON in the above formats? I can not create 2 endpoints.
The easier way is to define Month as an optional property.
paths:
/report:
parameters:
...
get:
responses:
200:
description: OK
schema:
type: array
items:
$ref: '#/definitions/ReportEntry'
definitions:
ReportEntry:
type: object
properties:
Month:
type: string
example: Jan
Details:
type: array
items:
$ref: '#/definitions/UserInfo'
required:
- Details # <---- "Details" is required, "Month" is optional
UserInfo:
type: object
properties:
userId:
type: integer
example: 12345
userName:
type: string
example: ABC
required:
- userId
- userName
I'm trying to use swagger to describe a rest api I added to some code.
This is one of my simple returns.
Saw a couple good examples but didn't have any luck trying to make sense how to apply it to my problem.
The different API calls will contain different content.
If I know what this one should look like I aught to be able to figure the others out.
Can anyone tell me what this description should look like?
{
"result" : {
"content" : {
"UNTAINTED_HOST" : "www.google.com",
"DATA" : [
"216.58.217.36"
],
"IP_or_NAME" : "NAME",
"RC" : "true",
"FAULT_MSG" : "No Faults"
},
"detail" : "Sucessfully terminated your request",
"short" : "Done" }
}
Or this even simpler one:
{
"result" : {
"short" : "Done",
"detail" : "Sucessfully terminated your request",
"content" : "Running"
}
}
Think it would look like -
{
"definitions": {
"result": {
"type": "object",
"required": [
"short", "detail", "content"
],
"properties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"detail": {
"type": "string"
},
"short": {
"type": "string"
},
}
}
}
}
}
}
Tried this in the swagger editor... seems I missed something.
definitions:
results:
type: object
required: [ result ]
properties:
result:
type: array
items:
$ref: #/definitions/result
result:
type: object
properties:
short:
type: string
detail:
type: string
content:
type: string
This seemed to work:
results:
type: object
required: [ result ]
properties:
result:
type: array
items:
type: object
required: [ short, detail, content ]
properties:
short:
type: string
detail:
type: string
content:
type: string
Thanks
This worked for me:
definitions:
result:
type: object
properties:
short:
type: string
detail:
type: string
content:
type: string
results:
type: object
required: [result]
properties:
result:
type: array
items:
$ref: '#/definitions/result'
Notice the single quotes around the value of $ref. I didn't see those in your original post. However, you didn't mention the error you are seeing. If this answer doesn't help, please update your question with more details.
i have a JSON response from remote server in this way:
{
"string": [
{
"id": 223,
"name": "String",
"sug": "string",
"description": "string",
"jId": 530,
"pcs": [{
"id": 24723,
"name": "String",
"sug": "string"
}]
}, {
"id": 247944,
"name": "String",
"sug": "string",
"description": "string",
"jlId": 531,
"pcs": [{
"id": 24744,
"name": "String",
"sug": "string"
}]
}
]
}
In order to parse the response, to list out the "name" & "description", i have written this code out:
interface MyObj {
name: string
desc: string
}
let obj: MyObj = JSON.parse(data.toString());
My question is how do i obtain the name and description into a list that can be displayed.
You gave incorrect type to your parsed data. Should be something like this:
interface MyObj {
name: string
description: string
}
let obj: { string: MyObj[] } = JSON.parse(data.toString());
So it's not MyObj, it's object with property string containing array of MyObj. Than you can access this data like this:
console.log(obj.string[0].name, obj.string[0].description);
Instead of using anonymous type, you can also define interface for it:
interface MyRootObj {
string: MyObj[];
}
let obj: MyRootObj = JSON.parse(data.toString());