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 have found several official AWS documents that describe some of the structure/schema for specifying models in Yaml files. For example:
https://docs.aws.amazon.com/apigateway/latest/developerguide/models-mappings.html
https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-api.html#sam-resource-api--examples--simpleapiexample--yaml
In particular, the first document says this at the end:
The examples don't use advanced JSON schema features, such as specifying required items, minimums and maximums (for allowed string lengths, numeric values, and array item lengths), and regular expressions. For more information, see Introducing JSON and JSON schema draft 4.
and links out to https://www.json.org/json-en.html and https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04
Neither of those documents describe anything about required items, minimums and maximums, or any of these other "advanced" JSON schema features.
Is there some canonical reference that shows what is possible when describing models in a yaml file, and what the syntax is? How does anyone know what to type? For example, when writing a model, how does anyone know that:
MyModel:
description: this is an object with one property
type: object
properties:
grade:
type: integer
is correct. while:
MyModel:
description: this is an object with one property
type: object
properties:
grade:
type: int
is not correct?
The AWS page is indeed a bit poorly worded. "JSON Schema" is the name of a set of specifications, and "Draft 4" is a particular version of those specifications. (The name "draft" is something of a misnomer, which exists for historic and bureaucratic reasons, so you can read that as "Version 4" or "Release 4".)
The home page for JSON Schema is at https://json-schema.org where you can find the current version of the base specification (which just describes the general format) and the validation specification, which is what you were looking for.
For older versions, you need to look at https://json-schema.org/specification-links.html so if the AWS documentation is correct that API Gateway only supports Draft 4 (from about 10 years ago), the more useful page to link to would have been this: https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00
We use swashbuckle to generate our API's document and swagger page.
One API takes an enum as parameter, and the swagger document will generate a list of all possible enum values.
PerformanceEndType (string, optional): The descriptions we put in. ['DayEnd', 'MonthEnd', 'QuarterEnd', 'YearEnd'],
In the description, we have a link which shows details about the enum, so I wants to hide the enum list swashbuckle gives us.
However, seems swashbuckle doesn't have an option to turn this on and off. I checked DescribeAllEnumsAsStrings but that doesn't really do what I want.
Is there a way to annotate my C# code to specify an array is a required parameter and should have at least one item?
It currently shows as optional in Swagger.
I am using Swashbuckle.AspNetCore 1.2.0
Thanks!
Wrapping the parameters in a DTO allows each field to be annotated. In the case of an IEnumerable<> field, it can be annotated with [MinLength(1)], which then carries over to the Swagger.
While this was supported on Swashbuckle:
https://github.com/domaindrivendev/Swashbuckle/search?q=minItems
It does not seem to be the case on Swashbuckle.AspNetCore
https://github.com/domaindrivendev/Swashbuckle.AspNetCore/search?q=minItems
Your only option is to request it as a new feature, and hopefully they will add it soon:
https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/new
Is there a C++ library I use to load the XSD schema model?
The goal is to load the actual XSD schema model (eventually from multiple files) in a way that I can then inspect the model elements (i.e., types, cardinality, attributes, even comments if possible). I don't want to use it for XML content but to manipulate/inspect the actual model.
I know that in Java it can be done, for example, with Xerces2 (http://xerces.apache.org/xerces2-j/xml-schema.html), but I looked for something similar in C++ and could not find it.
You could look at the C++ implementation of EMF:
http://modeling-languages.com/emf4cpp-c-implementation-emf/
Then you could use the EMF XSD model:
http://www.eclipse.org/modeling/mdt/?project=xsd
The EMF XSD model is very well engineered, so the only question is around the maturity of the C++ port of EMF.
This page lists the following examples:
Addition of new WSDL operations to an existing WSDL document
Addition of new XML schema types within a WSDL document that are not contained within previously existing types
But is there a definition or standard
guideline for what changes are considered backwards-compatible. Or in other words, what changes can you make to your contract, and still expect not to break your clients.
I have spent some time on this particular subject, and found some guidelines in a book by Thomas Erl which I refer to at the bottom. Here is what they have to say;
Compatible Changes
adding a new WSDL operation definition and associated message definitions
adding a new WSDL port type definition and associated operation definitions
adding new WSDL binding and service definitions
adding a new optional XML Schema element or attribute declaration to a message definition
reducing the constraint granularity of an XML Schema element or attribute of a message definition type
adding a new XML Schema wildcard to a message definition type
adding a new optional WS-Policy assertion
adding a new WS-Policy alternative
Incompatible Changes
renaming an existing WSDL operation definition
removing an existing WSDL operation definition
changing the MEP of an existing WSDL operation definition
adding a fault message to an existing WSDL operation definition
adding a new required XML Schema element or attribute declaration to a message
definition
increasing the constraint granularity of an XML Schema element or attribute declaration
of a message definition
renaming an optional or required XML Schema element or attribute in a message
definition
removing an optional or required XML Schema element or attribute or wildcard
from a message definition
adding a new required WS-Policy assertion or expression
adding a new ignorable WS-Policy expression (most of the time)
There is a great book on this particular subject from Thomas Erl et al; The name is Web Service Contract Design & Versioning for SOA.
HTH.
Disclaimer: As I've mentioned, this is work done by the authors of the book and I'm merely sharing it. I'm also not affiliated in anyway; just liked the book :)
Additional optional request elements (minoccurs=0) could also be backward compatible - this depends on the implementation of the service on the host side.
Also, changing a mandatory response element to optional could also be backward compatible - it depends on the implementation of your client.
This area is tricky.
If you are really worried about backward compatibility consider creating a new version of the service for new clients and keep the existing implementation for existing clients. Also, in general, avoid sending domain objects over your services - use DTOs.
Hope this helps.