1.2 transition

==========

Not to be confused with the swagger framework versioning, the swagger specification itself is versioned for compatibility. You can see information about previous versions in the wiki.

Philosophically, any changes to the spec are absorbed into the tools for one-version backwards compatibility. So the swagger-ui will work with both swagger-spec 1.1 and 1.2. It is not tested against older versions (prior to 1.1). Changing a specification typically causes some heartache and pain, so the changes introduced are usually not just for fun--they have a history of issues or confusion behind them, which mandates the change.

You can use the swagger-codegen to migrate your swagger 1.1 spec! Please see HERE for details.

That said, here's a transition guide for the 1.2 specification.

1.0 Resource Listing

Changes

• The swaggerVersion should report 1.2 for proper detection.

• The resource listing no longer requires a basePath.

• The path element now supports relative and absolute paths. Relative paths are considered to be relative to the Resource Listing.

Why the changes?

The absolute path allows Resource Listings to easily point to multiple servers, so a Resource Listing can be an "uber directory" of apis. Next, the basePath at the resource listing was serving a different purpose than at the Api Declaration, causing much confusion. Finally, the basePath for Resource Listing was an additional configuration to mess up.

Additions

• An authorizations section was added to define what authorization schemes were supported for the API. See the authorizations section for details on this section. It is not required for 1.2 compliance.

• An info section was added to define metadata about the API. It too is optional but highly recommended--the metadata is also presented directly in the swagger-ui console for easy access. See the API Info section for details.

2.0 API Declaration

Changes

• The swaggerVersion should report 1.2 for proper detection.

• The resourcePath now must start with a forward slash "/"

• The path inside the apis array must start with a forward slash

• Each operation element can contain an optional responseMessages value. This was renamed from errorResponses.

• The parameters has been updated to support JSON-schema v4 format. See the Models section for details.

• Each element in the responseMessages array contains an integer code and string message field. Previously, the analogous errorResponse attributes were named code and reason respectively.

• The responseMessage element may contain an optional responseModel attribute to indicate a different object type as a return value depending on the code which typically maps to http response codes.

• The dataType field has been renamed to type for consistency with the JSON-schema v4 draft spec. See section 2.1 for more details

• The allowableValues field has been absorbed into an enum for LIST type, and minimum + maximum for ranges

Additions

• The API Declaration supports a produces array, which is an array of strings. These apply to all operations in the API unless overridden at the API level.

• The API Declaration supports a consumes array, which is an array of strings. These apply to all operations in the API unless overridden at the API level.

• Elements in the operations array can contain the following arrays: consumes, produces, authorizations, protocols. These values override any existing values at the API Declaration

Why the changes?

The path and resourcePath attributes were inconsistent with leading slashes, causing unnecessary validations.

For the errorResponses array, many non-200 response codes are actually not errors. This made the reason not make sense (reason implies an error state) and often different response codes need to return different data. Such as a 400 response code might include information as to why in the payload.

2.1 API Declaration models

Additions

• Models are now described with JSON-Schema Draft 4. This creates multiple changes:

• Datatypes now conform to the JSON Schema specification. The use of the format attribute is used to make up for the more coarse-grained type specification, as shown after the comma in Swagger spec 1.2 below.

Common name	Swagger spec 1.2	Swagger spec 1.1
integer	integer, int32	int
long	integer, int64	long
float	number, float	float
double	number, double	double
string	string	string
byte	string, byte	byte
boolean	boolean	boolean
date	string, date	Date
dateTime	string, date-time	Date

• Required fields are now annotated at the model-level as opposed to the field level. For example, the id and name fields are required:

"Pet" : {
  "id" : "Pet",
  "required" : [
    "id",
    "name"
  ],
  "properties" : {
    "name" : {
      "type" : "string"
    },

• Containers have a slightly different representation from the 1.1 spec, again changed to reflect the JSON-schema draft-4

Common name	Swagger spec 1.2	Swagger spec 1.1
List	array	List
Array	array	Array
Set	array, uniqueItems=true	Set

• Models can now contain a subTypes attribute which indicate that models are a subtype another. It is assumed that the subclass contains the union of properties between itself and its superclass

• Models can contain a discriminator field which, in conjunction with a subTypes, can be used for polymorphic models.

Why the changes?

The model specification as JSON-schema opens the ability for more consistent model descriptions. The previous version of swagger models was based on a JSON-schema draft but it has been brought up to spec with draft-4, which is gaining good adoption.

3.0 Credits

These changes are introduced largely by the swagger community. They reflect a lot of hard work, convincing, emails, IRC chats, and good intentions. If you use swagger, thank your fellow swagger contributors!