I'm building an OpenAPI (Swagger) 2.0 definition for the following XML payload to use within the Swagger UI:
<addressElement>
<key type="RECORD_ID" item="3">Enter value here</key>
</addressElement>
I'm having an issue figuring out how to display the default value 'Enter value here' for the element key. Where would one place this default value in an OpenAPI definition? My definition looks like this:
"definitions": {
"addressElement": {
"type": "object",
"title": "Address Element",
"properties": {
"key": {
"type": "object",
"properties": {
"type":{
"type": "string",
"example": "RECORD_ID",
"xml":{
"attribute": true
}
},
"item":{
"type": "integer",
"format": "int64",
"example": "3",
"xml":{
"attribute": true
}
}
}
},
},
"xml": {
"name": "addressElement"
}
}
}
This is currently not possible because OpenAPI does not have a way to represent XML elements with attributes such as
<key type="RECORD_ID" item="3">Enter value here</key>
Attributes can only be defined for objects
<obj attr="value">
<elem>Some text</elem>
</obj>
but not for simple <elem>text</elem> elements.
There's an open issue about this limitation here:
How to represent XML elements with attributes
That said, OpenAPI Specification maintainers are considering an option to use alternative data modeling schemas (such as XSD Schema), so your use case might be supported in a future version of OpenAPI.
Related
I am facing a strange issue that I extract a schema of api response and added json file in my serenity project. While validating schema, what ever the schema provided the test was passing, moreover if I changed any type of key like I change the data-type of any key value correct schema( like changed the name data-type from string to integer) then test failed.
Scenario:
My API response:
{
"name":"Alex",
"age" : 20,
"city":"New York"
}
My Schema for this API: Test Passed which is ok
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "integer"
},
"city": {
"type": "string"
}
},
"required": [
"name",
"age",
"city"
]
}
If I changed the schema from correct to wrong that is remove any key value pair the test even passed which is not correct
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"city": {
"type": "string"
}
},
"required": [
"name",
"city"
]
}
Moreover if I write only " { } " in the Schema file the test passed
The method I am using for validation is matchesJsonSchemaInClassPath
The schema validation only checks the data-types that are coming for values in JSON are correct by matching with schema. For the data validation there is another method in Serenity BDD that is VerifyResponseData.ofTheresponse(jsonobj)
This works for me
I am using Swagger Editor to work on a JSON Swagger 2.0 API definition. I have reduced my definition to a minimum example of the problem I am experiencing. The problem occurs when I use a reference object to define a path parameter that is shared between multiple endpoints.
Example endpoints:
/my-api/{id}/some-thing
/my-api/{id}/some-other-thing
Since these id parameters are defined the same way, I abstracted them to the parameters section of the JSON file, and included them with "$ref": "#/parameters/testObjectId".
The Swagger reduced definition shows this:
{
"swagger": "2.0",
"info": {
"title": "Test Service",
"description": "REST API for TestObjects",
"version": "1.0.0"
},
"host": "api.not-a-real-url.com",
"schemes": [
"https"
],
"basePath": "/api/test-objects",
"produces": [
"application/hal+json"
],
"consumes": [
"application/json"
],
"paths": {
"/{id}": {
"get": {
"operationId": "getTestObject",
"summary": "Get a TestObject resource referenced by slug string ID",
"security": [],
"parameters": [
{
"$ref": "#/parameters/testObjectId"
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"type": "object",
"properties": {}
}
},
"default": {
"description": "Error",
"schema": {
"type": "object",
"properties": {}
}
}
}
}
}
},
"parameters": {
"testObjectId": {
"name": "id",
"in": "path",
"required": true,
"type": "string",
"format": "slug",
"description": "Immutable, unique identifier of a TestObject"
}
},
"definitions": {
}
}
But when this is rendered in Swagger, I get the following error:
Errors
Semantic error at paths./{id}
Declared path parameter "id" needs to be defined as a path parameter at either the path or operation level
The problem is that id is actually defined, only it appears that the check which throws this error is occurring before the $ref is included. The Swagger output looks correct.
Further, I have used this approach for about 6 months (as long as I have used Swagger) and I am just now running into the problem for the first time. Is there something I should be doing differently to prevent this error? Am I misusing Swagger by doing it this way?
Your spec is valid. It was a bug introduced in Swagger Editor v.3.2.2, it was fixed in v.3.2.3 (released on January 6, 2018).
I have a simple schema as follows:
{
"name": "owner",
"type": "record",
"doc": "todo",
"fields": [
{ "name": "version", "type": "int", "default": 1},
{ "name": "name", "type": "string" },
{ "name": "age", "type": "int" },
]
}
However when I use the avro-maven-plugin to generate a java object from this specificaion, it does not set the default value of version field to 1.
How do I make that happen?
Nevermind, It works fine as is.
I was looking at the generated Java class, and could not figure out where it was setting the default value to 1. But when I serialize it using json, I see the default value in the output. Also, the getter returns the default value as well.
We are using Swagger 2.0 for our documentation. We are Pro-grammatically creating swagger 2.0 spec straight out our data design documents.
Our Model is very complex and nested. I would like to understand can we define nested array objects defined inline.
for e.g :
{
"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"
}
},
"Person": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
}
}
}
}
}
}
}
}
We have many cases where we encounter this in our model and defining a #ref is not an option that we want to consider at this time. We need this to handled inline.
As per the following post : https://github.com/swagger-api/swagger-editor/issues/603#evenenter code heret-391465196 looks like its not supported to handle nested array objects defined inline.
Since lot of big enterprise's have a very complex data model we would like to have this this feature to be supported in swagger 2.0 spec.
Is there any thought on this feature to be added.
You document is just invalid and this is not about nested arrays: the property Person is not allowed in a Swagger 2.0 schema inside items.
The only allowed properties in a schema are: $ref, format, title, description, default, multipleOf, maximum, exclusiveMaximum, minimum, exclusiveMinimum, maxLength, minLength, pattern, maxItems, minItems, uniqueItems, maxProperties, minProperties, required, enum, additionalProperties, type, items, allOf, properties, discriminator, readOnly, xml, externalDocs, example.
This is the description of a certain parameter I have:
{
"name": "myParam",
"description": "My param description",
"required": true,
"paramType": "query",
"type": "string",
"defaultValue":"myValue"
}
The defaultValue is the only value the parameter can have, so is there a way to declare this? Seen in the context of the swagger-ui, I need the parameter's textbox to be read-only. I'm using swagger 1.2.
Thanks
The proper way to declare this would be:
{
"name": "myParam",
"description": "My param description",
"required": true,
"paramType": "query",
"type": "string",
"enum": [ "myValue" ]
}
The "enum" property sets the possible values. Once you set a single value to it, that's the only one that could be used and that would be available in the UI for the user to choose from.
I'm a bit late to the game but with OpenAPI 3.1 you can do the following:
defaultValue:
type: string
const:
- myValue
You can also use 'pattern' of the string to avoid the enum - this could look better in Swagger:
{
"openapi": "3.0.0",
"components": {
"schemas": {
"object": {
"type": "object",
"required": [
"myParam"
],
"properties": {
"myParam": {
"type": "string",
"pattern": "onlyAllowedValue$"
}
}
}
}
}
}