One of my objects in response is kept as empty. I am unable to create the swagger yaml for that part.
... <<something>>
,
"dummy": [
{}
],
... <<something>>
I have written below piece:
..... <<something>>
dummy:
$ref: '#/definitions/dummy'
..... <<something>>
dummy:
type: array
items:
$ref: "#/definitions/dumm"
dumm:
properties:
type: "object"
The error seen is "should be object" in front of the last line above.
How to resolve this?
The correct definition of your model would be:
dummy:
type: array
items:
$ref: "#/definitions/dumm"
dumm:
type: "object"
Do not use properties if the model does not have any of them.
Related
I have the following component defined in OpenAPI:
Template:
type: object
properties:
Callback:
description: 'If set, this url will be called with a POST when a job completes. If the text "{guid}" is in the url, that text will be replaced with the Guid for the callback.'
type: string
OutputFormat:
type: string
description: 'Generate the document in the provided format.'
enum: [pdf, docx, xlsx, pptx, txt, html, prn, csv, rtf, jpg, png, svg, eps, bmp, gif]
Data:
description: 'The source of the template- embedded or external. Embed template as a Base64-encoded string.'
type: string
format: base64
ConnectionString:
description: "Set this to provide the template as a connection string of the template's location."
type: string
Format:
type: string
description: 'Format of the template. Auto-determined if not provided.'
enum: [docx, html, xlsx, pptx]
Properties:
description: "Windward properties for this document. These override any properties set in the configuration file on the server side."
type: array
items:
$ref: '#/components/schemas/Property'
xml:
wrapped: true
Parameters:
description: "A set of input parameters for this document. The parameters are global and shared among all data sources."
type: array
items:
$ref: '#/components/schemas/Parameter'
xml:
wrapped: true
Datasources:
description: "The datasources to apply to the template. The datasources are applied simultaneously."
type: array
items:
$ref: '#/components/schemas/Datasource'
xml:
wrapped: true
Tag:
type: string
description: "Anything you want. This is passed in to the repository & job handlers and is set in the final generated document object. The RESTful engine ignores this setting, it is for the caller's use."
TrackImports:
type: boolean
description: "Return all imports with the generated document."
TrackErrors:
type: integer
minimum: 0
maximum: 3
description: "Enable or disable the error handling and verify functionality."
MainPrinter:
type: string
description: "If you are using printer output use to specify main printer. Printer must be recognized by Network"
FirstPagePrinter:
type: string
description: "Set first page printer if main printer is already set"
PrinterJobName:
type: string
description: "Assign print job name"
PrintCopies:
type: integer
description: "Set number of copies to print"
PrintDuplex:
type: string
description: "Selects the printer duplex mode. Only if supported by the printer."
If you take a look at the Datasources entry, it is an array of Datasource component:
Datasources:
description: "The datasources to apply to the template. The datasources are applied
simultaneously."
type: array
items:
$ref: '#/components/schemas/Datasource'
I am trying to define an example request body for the POST request (the body you send is the template component I showed above). When I try to define the example values, this is what it looks like:
And this is what it renders to:
The problem is that it is showing it as a dictionary of dictionaries (with the "{}" brackets). I need it to be an array of dictionaries (with the "[]" on the outside). Does anyone know how to do this?
I tried doing this:
but Swagger Editor doesnt like that. Any ideas?
Just to make it clearer, this is what im trying to do:
# I NEED THIS
Datasources: [
Datasource: {
Name: "...",
Type: "..."
}
]
# INSTEAD OF THIS
Datasources: {
Datasource: {
Name: "...",
Type: "..."
}
}
Here's how to write an array (sequence) of objects in YAML. Note the dash before each array item.
example:
...
Datasources:
- Name:
Type: json
ConnectionString: some value
- Name: Name2
Type: yaml
ConnectionString: some other value
...
You can also use JSON array syntax [ ... ], but in this case the array must be written as valid JSON, that is, array items must be comma-separated, nested objects must be written as { ... } with all key names and string values enclosed in quotes, and so on.
example:
...
Datasources: [
{
"Name": null,
"Type": "json",
"ConnectionString": "some value"
},
{
"Name": "Name2",
"Type": "yaml",
"ConnectionString": "some other value"
}
]
Tag: ...
In swaggerhub I am trying to build a restful API. For which I have created n number of POJOs for request. I would like to represent them as references in other POJO example:
ClientInformation:
type: object
schema:
$ref: '#/definitions/EditClient'
$ref: '#/definitions/OtherDetails' #Duplicate mapping key error I see at this line
properties:
notes:
type: string
example: This is a test
description: A description
I tried , but didn't work. Kindly suggest.
If ClientInformation is a merger of the EditClient and OtherDetails schemas, you need allOf:
ClientInformation:
allOf:
- $ref: '#/definitions/EditClient'
- $ref: '#/definitions/OtherDetails'
- type: object
properties:
notes:
type: string
example: This is a test
description: A description
If ClientInformation has properties that are instances of other schemas, you can $ref the property schemas as follows:
ClientInformation:
type: object
properties:
notes:
type: string
example: This is a test
description: A description
foo:
$ref: '#/definitions/EditClient'
bar:
$ref: '#/definitions/OtherDetails'
I am currently learning how to document using Swagger because my company is evaluating using it as a standard way of documenting for upcoming projects.
I read online that using YAML is easier to read than using JSON, and since YAML is a subset of JSON I figured it would be alright.
I'm working on the response for the 200 code, I would like to represent something similar to the following structure:
responses:
200:
description: OK.
schema:
title: response
type: object
items:
properties:
title: user
type: array
items:
id:
type: string
name:
type: string
status:
type: integer
Basically I return an object called "response" that contains two variables: An array called "user" that contains several strings (I included just two for the sake of clarity) and another variable (outside of the "user" array) called "status" that contains an integer.
The above code doesn't work, and the editor notifies me that it isn't a "valid response definition".
I'm not sure how to tackle this. I'd appreciate some help on what I'm doing wrong.
Basically I return an object called "response" that contains two variables: An array called "user" that contains several strings (I included just two for the sake of clarity) and another variable (outside of the "user" array) called "status" that contains an integer.
Based on your description, the response is supposed to be as follows (assuming the response is JSON). Basically, you have an object with a nested object:
{
"user": {
"id": "12345",
"name": "Alice"
},
"status": 0
}
This response can be defined as follows:
responses:
200:
description: OK.
schema:
title: response
type: object
required: [user, status]
properties:
user:
type: object
required: [id, name]
properties:
id:
type: string
name:
type: string
status:
type: integer
For convenience, complex schemas with nested objects can be broken down into individual object schemas. Schemas can be written in the global definitions section and referenced from other places via $ref. This way, for example, you can reuse the same schema in multiple operations/responses.
responses:
200:
description: OK.
schema:
$ref: "#/definitions/ResponseModel"
definitions:
ResponseModel:
title: response
type: object
properties:
user:
$ref: "#/definitions/User"
status:
type: integer
required:
- user
- status
User:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
I am quite new to Swagger, so this might be a basic question.
I am able to create .yml file for an API which takes an array of integers as parameter, as follows:
Add samples
---
tags:
- MY API
parameters:
- name: my_id
in: path
type: integer
required: true
description: Some des
- name: body
in: body
schema:
id: add_samples
required:
- sample_ids
properties:
sample_ids:
type: array
items:
type: integer
description: A list of sample ids to be added
responses:
'200':
description: Added samples.
'400':
description: Error adding samples.
This is what I send to the above API and everything works fine:
{"sample_ids": [475690,475689,475688]}
Now, instead of an array of integers, if I want to use some complex object as parameter, how to do it?
E.g. If this is what I want to send:
{"sample_ids": [{
"sample_id": "7",
"some_prop": "123"
},
{
"sample_id": "17",
"some_prop": "134"
}]}
How should the .yml file look? I have tried something like this and it doesn't seem to work:
Add sample
---
tags:
- Samples API
models:
Sample:
id: Sample
properties:
sample_id:
type: string
default: ""
description: The id for this sample
some_prop:
type: integer
description: Some prop this sample
parameters:
- name: body
in: body
schema:
id: add_sample
required:
- sample_ids
properties:
samples:
type: array
description: A list of samples to be added
items:
$ref: Sample
responses:
'201':
description: Created a new sample with the provided parameters
'400':
description: SOME ERROR CODE
This one seems to work, mostly:
Add sample
---
tags:
- Samples API
models:
Sample:
id: Sample
properties:
sample_id:
type: string
default: ""
description: The id for this sample
some_prop:
type: integer
description: Some prop this sample
parameters:
- name: body
in: body
schema:
id: add_sample
required:
- sample_ids
properties:
samples:
type: array
description: A list of samples to be added
items:
$ref: Sample
responses:
'201':
description: Created a new sample with the provided parameters
'400':
description: SOME ERROR CODE
Now only problem is, in the Swagger UI, it is not showing member variables and their default values. Rather is showing it as null:
{
"samples": [
null
]
}
I am trying to create a Response Object that looks like this:
(simplified for example)
{
"data1": "1234"
"data2" : "445"
}
I have 2 definitions:
obj1:
type: object
properties:
data1:
type: string
obj2:
type: object
properties:
data2:
type: string
Then a 3rd definition that looks like this:
Main:
type: object
allOf:
- $ref: "#/definitions/ob1"
- $ref: "#/definitions/obj2"
I'm not sure if this is the correct way to merge both Obj1 and Obj 2 at the base of the Main object
The Swagger UI show the following
Responses
Code Description Schema
200 Success ⇄
Main {
all of:
obj1 { }
obj2 { }
}
What I'm unclear about is if it will set these objects at the root or if its stating 2 objects will be in the response???
I'm assuming its correct, hoping someone can confirm.
Swagger allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes in an array of object definitions that are validated independently but together compose a single object.
According to this - Swagger UI shows two objects which in fact be composed into one object with combined properties. You can try it by yourself:
StringObj:
type: object
properties:
stringId:
type: string
IntegerObj:
type: object
properties:
integerId:
type: integer
Composed:
description: A representation of a dog
allOf:
- $ref: '#/definitions/StringObj'
- $ref: '#/definitions/IntegerObj'
If you use Composed in - for example - body of your method and use try this operation Swagger creates json:
{
"stringId": "aaa",
"integerId": 123
}