Assume I have following schema to reuse later using $ref:
"schemas": {
"Order": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"petId": {
"type": "integer",
"format": "int64"
}
}
}
But I have another schema similar to this:
"schemas": {
"Order": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"itemId": {
"type": "integer",
"format": "int64"
}
}
}
Only difference between them is itemId and petId, I want to create only one schema and pass itemId or petId when referencing.
How to accomplish this? Are there any alternative solutions?
There's no way to pass arguments along a schema reference, really.
What we could do in your case is to have a base Order schema with just the common properties, and then separate schemas for petId/itemId Orders that utilize allOf.
Check this answer for another example (or this for a more concrete one!).
Related
I'm using swagger 2.0 and I have the following schema(definition) :
"User": {
"type": "object",
"properties": {
"firstName": {
"type": "string",
"example": "Tom"
},
"lastName": {
"type": "string",
"example": "Hanks"
},
"email": {
"type": "string",
"example": "Tom.Hanks#gmail.com"
},
"password": {
"type": "string",
"example": "azerty#123456"
}
}
and i want to refer to this schema in one of my responses, so i do the following:
"responses": {
"201": {
"description": "Created.",
"schema": {
"$ref": "#/definitions/User"
}
}
}
Until now everything works perfectly, but i don't want to expose the password property in the response schema. is the anyway to choose exactly the properties i want to use from the Userdefinition ?
No, there is no way. I'd suggest you define 2 types:
One type for user data without password, let's name it User.
And another type that inherits from it and contains additionally a password attribute. Let's name it UserWithCredential.
I have a rest service, that can work as below:
http://server/path/AddressResource and
http://server/path/AddressResource/someAnotherPath
I have a definitions like below.
"definitions": {
"address": {
"type": "object",
"properties": {
"street_address": { "type": "string" },
"city": { "type": "string" },
"state": { "type": "string" }
},
"required": ["street_address", "city", "state"]
}
}
that is the response of path1, and in path two i just want to return the "city" property of address.
Can I create a schema, referring to address and using just one of it's property?
I have the following model definitions in an OpenAPI/Swagger spec:
"definitions": {
"models.Equipment": {
"title": "Equipment",
"type": "object",
"properties": {
"Features": {
"type": "array",
"items": {
"$ref": "#/definitions/models.Feature"
}
},
"Id": {
"type": "integer",
"format": "int64"
},
"IdType": {
"type": "string"
},
"Name": {
"type": "string"
},
"Price": {
"type": "integer",
"format": "int32"
}
}
},
"models.Feature": {
"title": "Feature",
"type": "object",
"properties": {
"Equipments": {
"type": "array",
"items": {
"$ref": "#/definitions/models.Equipment"
}
},
"Id": {
"type": "integer",
"format": "int64"
},
"IdFeature": {
"$ref": "#/definitions/models.Feature"
},
"Name": {
"type": "string"
}
}
}
}
In the Feature model, he Equipments property is defined as an array of Equipment models, but Swagger UI 3.x renders it as an empty array []. Everywhere Feature model is used, like as examples for POST method in Feature I have this kind of display.
Is the definition incorrect in some way?
The complete spec is here:
https://dl.dropboxusercontent.com/s/anjfhgxhr0pfmnu/swagger-bug.json
This seems to be a bug in Swagger UI and is most likely caused by circular references in your models - models.Equipment references models.Feature, and models.Feature references models.Equipment. You can open an issue in the Swagger UI repository on GitHub.
Your spec also contains errors in the response definitions:
"responses": {
"200": {
"schema": {
"$ref": "#/definitions/models.Equipment"
}
},
"403": {}
}
Each response must have a description, so the correct version would be:
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/models.Equipment"
}
},
"403": {
"description": "Oops"
}
}
I am trying to fully comprehend indexing with multiple mapping types in ElasticSearch. In the docs it gives example code:
PUT my_index
{
"mappings": {
"user": {
"_all": { "enabled": false },
"properties": {
"title": { "type": "string" },
"name": { "type": "string" },
"age": { "type": "integer" }
}
},
"blogpost": {
"properties": {
"title": { "type": "string" },
"body": { "type": "string" },
"user_id": {
"type": "string",
"index": "not_analyzed"
},
"created": {
"type": "date",
"format": "strict_date_optional_time||epoch_millis"
}
}
}
}
}
With this mapping how would I then create and search on an object?
For create would it be:
POST my_index/user/blogspot
or
POST my_index/user,blogspot
For searching would it be:
GET my_index/user/blogspot
or
GET my_index/user,blogspot
or something else?
An example of a POST and GET with multiple mapping would really help me out. Thank you so much!
I'm trying to use Swagger to describe web-api I'm building.
The problem is that I can't understand how to describe complex json object?
For example, how to describe this objects:
{
name: "Jhon",
address: [
{
type: "home",
line1: "1st street"
},
{
type: "office",
line1: "2nd street"
}
]
}
Okay, so based on the comments above, you want the following schema:
{
"definitions": {
"user": {
"type": "object",
"required": [ "name" ],
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "array",
"items": {
"$ref": "#/definitions/address"
}
}
}
},
"address": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [ "home", "office" ]
},
"line1": {
"type": "string"
}
}
}
}
}
I've made a few assumptions to make the sample a bit more complicated, to help in the future.
For the "user" object, I've declared that the "name" field is mandatory. If, for example, you also need the address to be mandatory, you can change the definition to "required": [ "name", "address" ].
We basically use a subset of json-schema to describe the models. Of course not everyone knows it, but it's fairly simple to learn and use.
For the address type you can see I also set the limit to two options - either home or office. You can add anything to that list, or remove the "enum" entirely to remove that constraint.
When the "type" of a property is "array", you need to accompany it with "items" which declares the internal type of the array. In this case, I referenced another definition, but that definition could have been inline as well. It's normally easier to maintain that way, especially if you need the "address" definition alone or within other models.
As requested, the inline version:
{
"definitions": {
"user": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"home",
"office"
]
},
"line1": {
"type": "string"
}
}
}
}
}
}
}
}