I am not able to nest $ref files in Swagger 2.0.
I am trying to define my API where-in I have provided the first $ref statement:
definitions:
collection-response:
type: "object"
properties:
response-status:
$ref: './schema/response-status.schema'
The response-status.schema is a separate file in the schema folder.
response-status.schema is defined as below:
{
"type": "object",
"properties": {
"http-code": {
"type": "integer",
"description": "HTTP-Code being returned",
},
"error-block": {
"$ref": "error-block.schema"
}
}
}
Now Swagger-UI is not able to take the second nested $ref, which in this case is the file error-block.schema
Please help. Is this a wrong way of doing things?
What do I do in case I have such nested references?
Related
We want to have a system that allows us to define data schemas that we can use to validate our data, and to generate code in specific languages. We found json schema's that lets us do something like
File "message.json.schema"
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "Message",
"properties": {
"name": {
"type" : "string"
},
"type": {
"$ref": "type/message_type.schema.json"
},
"message_id":{
"$ref": "type/uuid.schema.json"
}
},
"required": ["name", "message_id"]
}
File "message_type.json.schema"
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "MessageType",
"enum": ["Message", "Query"]
}
File "uuid_type.json.schema"
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "UUID",
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
File "query.json.schema"
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "Query",
"allOf" : [ {"$ref": "type/message.schema.json" }],
"required": ["type"]
}
Please ignore if there is something that doesn't make sense but the point is, we really enjoy this system because it allows us to define types, and to refer to types that we create in another files, and even to use them like for type inheritance.
Then we want to use this files for code generation and validation. In python we then use a library called python_jsonschema_objects that can parse this files and the files that it references recursively, and we can then really simply create a python object with all the validation included.
But then we also want to use them for Java/Kotlin but the library that we found jsonschema2pojo doesn't seem able to parse linked files expecting everything to be in the same file.
This leads us to think that for some reason Json Schema is not that supported or used, unfortunately.
So, we have the question if a system like Avro or OpenAPI would be better supported and more widely used and could be chosen to this type of task.
I've got a POST endpoint described in Swagger and I want that endpoint to also have query parameters. We're using 1.2 swagger format because, well, legacy reasons. We use 3scale, it hosts the documents and you edit your swagger in their web UI. However, when I try to save the document it gives me the following error.
JSON Spec can not have paramType='body' and paramType='query' on the same method
I can't find anything in the swagger specs that says this is an actual limitation. Is this likely something specific to 3Scale or is this a general swagger limitation? And if the latter, can someone point me at a spec is that clarifies it?
The actual REST endpoint doesn't care, it's happy with query params on a POST. It's just getting the Swagger tool to be happy. Here's the abbreviated snippet of the swagger doc:
{
"parameters": [
{
"name": "myQueryParam",
"dataType": "string",
"paramType": "query",
"required": true
},
{
"name": "body",
"dataType": "string",
"paramType": "body",
"required": true
}
],
"httpMethod": "POST"
}
not sure if the error message is a generic validation error, but there a couple of error in the specification you shared:
it is "method" and not "httpMethod"
it is "type" and not "dataType"
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md
The following example works for me, but I use required=false:
{
"in": "query",
"name": "myQueryParam",
"required": false,
"type": "string"
}
See also Swagger parameters in query and/or body
I've got my Kafka Streams processing configuration for AUTO_REGISTER_SCHEMAS set to true.
I noticed in this auto generated schema it creates the following 2 types
{
"name": "id",
"type": {
"type": "string",
"avro.java.string": "String"
}
},
Could someone please explain why it creates 2 types and what exactly "avro.java.string": "String" is.
Thanks
By default Avro uses CharSequence for the String representation, the following syntax allows you to overwrite the default behavior and use java.lang.String as the String type for the instances of the fields declared like this
"type": {
"type": "string",
"avro.java.string": "String"
}
I am using npm nswag to generate a TypeScript file from a Swagger .json file with the swaggerToTypeScriptClient code generator.
There is a problem when it comes across OData properties contained in the JSON. When it generates the interface, the TypeScript throws an error because it does not recognise the '#' in the OData property value.
This is an example of the original Swagger .json:
"Swashbuckle.OData.ODataResponse[System.Collections.Generic.List[Shadow.DataLayer.ReleaseBatchs]]": {
"type": "object",
"properties": {
"#odata.context": {
"type": "string"
},
"value": {
"type": "array",
"items": {
"$ref": "#/definitions/Shadow.DataLayer.ReleaseBatchs"
}
}
}
}
This is the corresponding TypeScript generated by the nswag swaggerToTypeScriptClient:
export interface ReleaseBatchs {
#odata.context?: string | undefined;
value?: ReleaseBatchs2[] | undefined;
}
This throws an error because it does not like the '#' in the property.
It would work if the generated code wrapped the property in quotes, like this:
export interface ReleaseBatchs {
"#odata.context"?: string | undefined;
value?: ReleaseBatchs2[] | undefined;
}
Is there a way to get the swaggerToTypeScriptClient to wrap these properties in quotes? Or to make it compatible with OData values?
This has been fixed in NSwag v11.3
I have an enum of other definitions in my Swagger spec:
"action": {
"title": "Action",
"description": "Action to apply to matching requests",
"type": "object",
"enum": [
{"delayAction": {"$ref": "#/definitions/delayAction"}},
{"abortAction": {"$ref": "#/definitions/abortAction"}},
{"traceAction": {"$ref": "#/definitions/traceAction"}}
]
}
and delayAction, abortAction, and traceAction are all defined.
But in the Swagger UI the model for action is empty.
How can I modify my Swagger definition so Swagger UI can show the definition of action in the model?
I think enums can be defined only as object literals.
Checkout this example it seems to explain quite well with an example.
https://community.smartbear.com/t5/Swagger-Open-Source-Tools/Enum-of-defined-objects/m-p/198117/highlight/true#M988