What is the equivalent of anyof in Swagger version 2.0, Please tell me how to update my json file because I want to upgrade my documentation from swagger 1.0 to 2.0.
Thank You for your Help.
I don't think there is one and it feels like a big shortcoming. It's definitely not mentioned in the Schema Object portion of the specification. They call out the elements there that have been adopted from the JSON Schema and anyOf isn't among them:
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
$ref - As a JSON Reference
format (See Data Type Formats for further details)
title
description (GFM syntax can be used for rich text representation)
default (Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object)
multipleOf
maximum
exclusiveMaximum
minimum
exclusiveMinimum
maxLength
minLength
pattern
maxItems
minItems
uniqueItems
maxProperties
minProperties
required
enum
type
The following properties are taken from the JSON Schema definition but their definitions were adjusted to the Swagger Specification. Their definition is the same as the one from JSON Schema, only where the original definition references the JSON Schema definition, the Schema Object definition is used instead.
items
allOf
properties
additionalProperties
I think the closest thing is the discriminator field, but that means you've got to structure your output to accommodate Swagger.
anyOf and oneOf are now supported in OpenAPI Specification 3.0 (released on July 26, 2017).
Related
I would like to add a description field to my dto (also to satisfy no_schema_description in OpenAPI linting), but find no way to do so. Which decorator to use? At the point of defining the dto or in the response?
Update (clarify): I am looking to define a description for the whole schema, not for single properties.
You can do that simply by using ApiProperty():
#ApiProperty({
description: 'The age of a cat',
})
age: number;
I recommend you to check the official doc openapi/types-and-parameters
In my API a UUID is not returned as its internal model instead it is returned as a string. This means if we have a UUID in the API it looks like
"uuid"
rather than:
{id: "uuid"}
Currently I tell springfox that UUID is a String, however this results in behavior where swagger seems to forget which strings are really UUIDs. Types which include a UUID in them, are changed so that instead they say they contain a string so the consumer of the swagger doc is no longer aware which parts of the json model is a UUID.
Does swagger support declaring types that are just a subset of a primitive, in this case I want to declare that the type UUID exists but tell swagger that a UUID just looks the same as a string?
Bonus question: if this is possible under swagger how can I declare this under springfox.
I was reading DWARFv4 spec and came across attribute DW_AT_endianity.
Correct me if my understanding is wrong.
As per spec, Two of the tag values TAG_variable and TAG_base_type both can have that attribute.
But as far as, i understand when you create a TAG_variable you have to pass the "Type", which can be of TAG_base_type(others are also possible).
So my question is if we are setting DW_AT_endianity on TAG_variable, why TAG_base_type also supports that attribute.
In other words every variable is of some type and can have that attribute, so why need attribute support for both type and variable?
The DW_AT_endianity attribute was the response to a proposed C compiler extension allowing the "creation of data in both big and little endian formats". It appears that the attribute was intended for base types (like this example) or structs/unions (like this one). Using the same attribute for both a simple variable and its underlying base type would, as you say, be redundant — note that the attribute is optional (see DWARF 4, sections 4.1.12 and 5.1).
Referencing OpenAPI 2.0, Schema Object, or Swagger 2.0, Schema Object, and the definition of discriminator field as:
Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the required property list. When used, the value MUST be the name of this schema or any schema that inherits it.
My confusions/ questions:
It is ambiguous to me, what role exactly it plays in inheritance or polymorphism. Could some one please explain discriminator with a working example showing what it exactly does and what if we do not use it? Any errors, warnings or any tools that depends on it for some operations?
Is it the case that swagger-editor does not support discriminator, and this field is used in some other tools?
What I have tried so far:
I have tried to use swagger-editor and the example from the same documentation (also mentioned below), to play around with this property to see if I can see any of its special behaviors. I changed the property, removed it, and extend the Dog model to one level deeper and tried the same on the new sub-model, but I did not see any changes in the preview of swagger-editor.
I tried searching online, and specially stackoverflow questions, but did not find any relevant information.
The sample code I used to do experiments:
definitions:
Pet:
type: object
discriminator: petType
properties:
name:
type: string
petType:
type: string
required:
- name
- petType
Cat:
description: A representation of a cat
allOf:
- $ref: '#/definitions/Pet'
- type: object
properties:
huntingSkill:
type: string
description: The measured skill for hunting
default: lazy
enum:
- clueless
- lazy
- adventurous
- aggressive
required:
- huntingSkill
Dog:
description: A representation of a dog
allOf:
- $ref: '#/definitions/Pet'
- type: object
properties:
packSize:
type: integer
format: int32
description: the size of the pack the dog is from
default: 0
minimum: 0
required:
- packSize
According to this google group, discriminator is used on top of the allOf property and it is defined in the super type for polymorphism. If discriminator is not used, the allOf keyword describes that a model contains the properties of other models for composition.
Just like in your sample code, Pet is a super type with property of petType identified as the discriminator and Cat is a sub type of Pet. Following is a json example of a Cat object:
{
"petType": "Cat",
"name": "Kitty"
}
The use of discriminator intends to indicate the property used to identify the type of an object. Assumes that there are tools that can proper support definition objects with the use of discriminator, it is possible to determine the type by scanning the property. For example, identify the object is a Cat according to petType.
However, the discriminator field is not well defined in the current version's specification or the samples (see issue #403). As far as I know, there is no tools provided by Swagger properly support it at the time being.
discriminator may be used if the model has a property used to determine the type. In this case, it is naturally fit and it can be used as an indicator for other developers understand the polymorphism relationship. If third party tools like ReDoc which support discriminator (see petType in this gif and example) is considered, you may find this useful.
The discriminator functionality has been much improved in OpenApi 3. You now provide a discriminator object which contains the name of the discriminator property, as well as a mapping of values of that property to schema names.
(I realize you did ask about OpenApi 2, but this is so much improved in 3 that hopefully you can make use of it).
See: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminatorObject for the v3.0.0 spec
Is there an ant task for generating an XSD from POJOs?
I'm presuming that you want to serialize a Java POJO object and then use XSD to validate the serialised XML data, or author new object instances which can instantiated via your de-serialization process.
Thing is Java XML serialization comes in two favours (Examples follow):
Xstream XML is dynamically generated from fixed object class description
XMLBeans Java classes dynamically generated from fixed XML Schema
Now perhaps you're using something else that combines both approaches?
What I'd recommend is create (or generate) an XSD based on the XML your object creates when serialized. Relatively speaking Java objects don't change that often and when they do a far great challenge is supporting multiple versions (Reading data encoded for the older version of your object). To address this challenge I'd recommend reading the following article for one possible solution:
http://java.dzone.com/articles/migrate-serialized-java