I'm getting the error Data does not match any schemas from 'oneOf' with the following spec:
{
"info": {
"version": "1.0.0",
"title": "REST API"
},
"paths": {
"/doit": {
"post": {
"responses": {
"200": {
"description": "Successful response"
}
},
"parameters": [
{
"type": "object",
"schema": {
"$ref": "#/definitions/ResponseDefinition"
},
"required": "true",
"name": "docs",
"in": "body"
}
]
}
}
},
"swagger": "2.0",
"definitions": {
"ResponseDefinition": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": ""
}
}
}
}
}
This full errorfrom the swagger-tools validator:
#/paths/~1doit/post/parameters/0: Data does not match any schemas from 'oneOf'
#/paths/~1doit/post/parameters/0: Data does not match any schemas from 'oneOf'
#/required: Expected type boolean but found type string
#/: Missing required property: type
#/paths/~1doit/post/parameters/0: Additional properties not allowed: in,name,required,schema
I don't understand the error or how to resolve.
You can't include type in a body parameter. That's why there's the schema. Try this:
{
"info": {
"version": "1.0.0",
"title": "REST API"
},
"paths": {
"/doit": {
"post": {
"responses": {
"200": {
"description": "Successful response"
}
},
"parameters": [
{
"schema": {
"$ref": "#/definitions/ResponseDefinition"
},
"required": "true",
"name": "docs",
"in": "body"
}
]
}
}
},
"swagger": "2.0",
"definitions": {
"ResponseDefinition": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": ""
}
}
}
}
}
For me it was incorrect apidoc that led to the error. This doc produced the error:
/**
* #openapi
* /init:
* get:
* description: Tells the app an environment it should use
* parameters:
* - name: version
* in: query
* description: app version, for example "4.0.0"
* required: true
* type: string
* responses:
* 200:
* description: Description
*/
Please note there is a type right under parameters
When I put type under parameters -> schema it started to be valid:
/**
* #openapi
* /init:
* get:
* description: Tells the app an environment it should use
* parameters:
* - name: version
* in: query
* description: app version, for example "4.0.0"
* required: true
* schema:
* type: string
* responses:
* 200:
* description: Description
*/
I realized I put wrong Model Bindings for my API.
I put FromQuery instead of FromBody
Related
I'm not very strong in swagger 2.0, could you please help me? I'm trying to describe body parameters, but got an error. Here is my swagger.json file:
{
"swagger": "2.0",
"info": {
"title": "Simple API overview",
"version": "v2"
},
"host": "localhost:4000",
"basePath": "/",
"paths": {
"/user/register": {
"post": {
"operationId": "register",
"summary": "User registration",
"parameters": [{
"in": "body",
"name": "role",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}]
}
}
}
}
When I try to run it, I got an error:
Error: Expected `string` for value, got `1`
If I remove example field, I got this in Example Value section:
{}
Looks like the type definition is incorrect, but I couldn't figure out what's the difference between my code and examples from swagger docs.
Any help is appreciated.
Thanks.
I found the reason: there should be consumes field defined as text/plain. By default it is application/json.
The full code:
{
"swagger": "2.0",
"info": {
"title": "Simple API overview",
"version": "v2"
},
"host": "localhost:4000",
"basePath": "/",
"paths": {
"/user/register": {
"post": {
"operationId": "register",
"summary": "User registration",
"consumes": ["text/plain"],
"parameters": [{
"in": "body",
"name": "role",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}]
}
}
}
}
One way to get around this error is to change type from integer to string.
"parameters": [{
"in": "body",
"name": "role",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}]
I'm currently writing swagger 3.0 documentation and using reDoc to render as nice UI for it. I have a few scenarios in my documentation where based on a previous properties enum I would want to display different schema object properties. Sadly I cant seam to figure out how to wire this together properly in my documentation. So far I have the following test endpoint:
{
"post": {
"operationId" : "test",
"summary": "test",
"description": "test",
"tags": [ "test" ],
"consumes": "application/json",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "./schemas/test1.json"
},
{
"$ref": "./schemas/test2.json"
}
],
"discriminator": {
"propertyName": "pet_type",
"mapping": {
"click": "./schemas/test1.json",
"open": "./schemas/test2.json"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success"
}
}
}
}
The test1.json looks like this:
{
"Cat": {
"type": "object",
"properties": {
"pet_type": {
"type": "string"
},
"hunts": {
"type": "boolean"
},
"age": {
"type": "integer"
}
},
"discriminator": {
"propertyName": "pet_type"
}
}
}
And the test2.json like this:
{
"Dog": {
"type": "object",
"properties": {
"pet_type": {
"type": "string"
},
"bark": {
"type": "boolean"
},
"breed": {
"type": "string",
"enum": [
"Dingo",
"Husky",
"Retriever",
"Shepherd"
]
}
},
"discriminator": {
"propertyName": "pet_type"
}
}
}
The desired out come would be to toggle between the two "test" jsons based on an enum (the drop down seen in the reDoc sample). What am I missing to get this result?
You can see an example of the discriminator result here under the feature section (the first gif)
After more digging I was able to figure out the issue... my structure for the most part.
On my index.json file I updated my components section to point at my components folder containing the schema as such:
"components": {
"$ref": "./components/test.json"
},
The test.json looks like the following:
{
"schemas": {
"Refinance": {
"description": "A representation of a cat",
"allOf": [
{
"$ref": "#/schemas/Pet"
},
{
"type": "object",
"properties": {
"huntingSkill": {
"type": "string",
"description": "The measured skill for hunting",
"default": "lazy",
"enum": [
"clueless",
"lazy",
"adventurous",
"aggressive"
]
}
},
"required": [
"huntingSkill"
]
}
]
},
"Purchase": {
"description": "A representation of a dog",
"allOf": [
{
"$ref": "#/schemas/Pet"
},
{
"type": "object",
"properties": {
"packSize": {
"type": "integer",
"format": "int32",
"description": "The size of the pack the dog is from",
"default": 1,
"minimum": 1
},
"foobar": {
"type": "string",
"description": "some ol bullshit"
}
},
"required": [
"packSize"
]
}
]
},
"Pet": {
"type": "object",
"discriminator": {
"propertyName": "petType"
},
"properties": {
"petType": {
"description": "Type of a pet",
"type": "string"
}
},
"xml": {
"name": "Pet"
}
}
}
}
And finally the schema for the endpoint gets referenced as follows:
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "../../index.json#/components/schemas/Pet"
}
}
}
},
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"
}
}
What is the best way to represent a generic response/payload object that has basic fields such as message, total elements, data, and status? Where the variability between each API is the data element. For instance, one API could be for permissions, so the data element would hold an array of permissions. But for another API, it would hold a different array of object types. My main goal is to have reuse with a payload object and to define the next "layer" of actual data.
I want to be able to define a data type that's generic - like a "response" that has basic fields but I want to be able to further define that content for each API (data containing permissions or roles or whatever).
Here are some JSON samples of what's been attempted but isn't rendering the way we would expect it to in Swagger UI (i.e. a flat structure of 4 elements with data defined per the API).
Example 1 - composition:
{
"swagger": "2.0",
"host": "localhost:8888",
"info": {
"version": "0.0.1",
"title": "API"
},
"paths": {
"/permissions": {
"get": {
"description": "Returns all permissions",
"operationId": "getPermissions",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "success",
"schema": {
"$ref": "#/definitions/permissionResponse"
}
}
}
}
}
},
"definitions": {
"response": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A string indicating the response from the server."
},
"totalElements": {
"type": "integer",
"format": "int64",
"description": "The number of items retrieved."
},
"status": {
"type": "string",
"description": "A string indicating the response from the server."
}
}
},
"permissionResponse": {
"allOf": [
{
"$ref": "#/definitions/response"
}, {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "The collection of items returned from the API request.",
"items": {
"$ref": "#/definitions/permission"
}
}
}
}
]
},
"permission": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "Unique identifier representing a specific permission."
},
"label": {
"type": "string",
"description": "The label of a permission."
},
"description": {
"type": "string",
"description": "A description of the permission."
},
"active": {
"type": "boolean",
"description": "A flag indicating whether a permission is active."
}
},
"required": [
"id",
"label",
"description",
"active"
]
}
}
}
Example 2 - composition variation:
{
"swagger": "2.0",
"host": "localhost:8888",
"info": {
"version": "0.0.1",
"title": "API"
},
"paths": {
"/permissions": {
"get": {
"description": "Returns all permissions",
"operationId": "getPermissions",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "success",
"schema": {
"$ref": "#/definitions/permissionResponse"
}
}
}
}
}
},
"definitions": {
"response": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A string indicating the response from the server."
},
"totalElements": {
"type": "integer",
"format": "int64",
"description": "The number of items retrieved."
},
"status": {
"type": "string",
"description": "A string indicating the response from the server."
}
}
},
"permissionResponse": {
"allOf": [
{
"$ref": "#/definitions/response"
}],
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "The collection of items returned from the API request.",
"items": {
"$ref": "#/definitions/permission"
}
}
}
},
"permission": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "Unique identifier representing a specific permission."
},
"label": {
"type": "string",
"description": "The label of a permission."
},
"description": {
"type": "string",
"description": "A description of the permission."
},
"active": {
"type": "boolean",
"description": "A flag indicating whether a permission is active."
}
},
"required": [
"id",
"label",
"description",
"active"
]
}
}
Example 3 - additional properties:
{
"swagger": "2.0",
"host": "localhost:8888",
"info": {
"version": "0.0.1",
"title": "API"
},
"paths": {
"/permissions": {
"get": {
"description": "Returns all permissions",
"operationId": "getPermissions",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "success",
"schema": {
"$ref": "#/definitions/permissionResponse"
}
}
}
}
}
},
"definitions": {
"response": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A string indicating the response from the server."
},
"totalElements": {
"type": "integer",
"format": "int64",
"description": "The number of items retrieved."
},
"status": {
"type": "string",
"description": "A string indicating the response from the server."
}
}
},
"permissionResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "The collection of items returned from the API request.",
"items": {
"$ref": "#/definitions/permission"
}
}
},
"additionalProperties": {
"$ref": "#/definitions/response"
}
},
"permission": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "Unique identifier representing a specific permission."
},
"label": {
"type": "string",
"description": "The label of a permission."
},
"description": {
"type": "string",
"description": "A description of the permission."
},
"active": {
"type": "boolean",
"description": "A flag indicating whether a permission is active."
}
},
"required": [
"id",
"label",
"description",
"active"
]
}
}
Example 1 renders well with swagger2markup showing the consolidated view of the data with the other 3 elements and having a permission array. However, with Swagger UI, it renders it differently, separating the objects out.
Markup rendered:
Swagger UI rendered
Swagger UI rendered - expanded
We are using swagger 2.0 to document our .Net Web API's which we are hosting in Azure behind Azure API Management. I am having troubles getting the documentation to detail the complex objects that are being posted as part of the body. Azure shows no details about the object at all leaving me to have to document them myself. Below is the json file that I imported into Azure API Management.
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Hotel Search",
"description": "The seodecnvewjkl"
},
"basePath": "/v1",
"consumes": [
"application/xml",
"application/json"
],
"produces": [
"application/xml",
"application/json"
],
"schemes": [
"http",
"https"
],
"paths": {
"/hotels/search": {
"post": {
"operationId": "searchCommand",
"description": "Searches for hotels",
"parameters": [
{
"name": "hotelSearchRq",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/HotelSearchRq"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"title": "HotelSearchRs",
"$ref": "#/definitions/HotelSearchRs"
}
},
"400": {
"description": "Bad Request"
},
"404": {
"description": "Unauthorised"
}
}
},
"get": {
"operationId": "searchQuery",
"parameters": [
{
"name": "CorrelationId",
"in": "query",
"type": "string"
}
],
"responses": {
"200": {
"description": "Successful response"
}
}
}
}
},
"definitions": {
"StayDetail": {
"type": "object",
"properties": {
"NumberOfGuests": {
"type": "integer"
},
"CheckinDate": {
"type": "string",
"format": "date",
"description": "the date that the stay starts from"
}
}
},
"HotelSearchCriteria": {
"type": "object",
"properties": {
"MaximumResults": {
"type": "integer",
"format": "int64"
},
"StayDetails": {
"$ref": "#/definitions/StayDetail"
}
}
},
"HotelSearchRq": {
"type": "object",
"properties": {
"CustomerTransactionIdentifier": {
"type": "string",
"description": "The customers transaction identifier"
},
"search_criteria": {
"$ref": "#/definitions/HotelSearchCriteria"
}
}
},
"HotelSearchRs": {
"type": "object"
}
}
}
Azure Api Management operation screen
Can someone please help me with how I can get the body documented automatically from the swagger documentation?
Currently the request and response body information from a Swagger doc are not displayed in the developer portal documentation.
This is no longer the case. Samples and schema are displayed in the developer portal.