Swagger 1.2 to 2.0 Migration Guide

Migration Guide

Swagger 1.2 (and previous versions) was made of two file types and Swagger 2.0 is made of one. To help seeing how fields were moved around, RL will be used to mark fields under the Resource Listing and AD will be used to mark fields under the API Declaration.

Field Migrations

Since some properties and objects are structurally differnt between 1.2 and 2.0, the field migration table below does not necessarily give a 1:1 translation. Instead, it may point you in the right direction. The table is meant as a reference guide only.

Original Field	New Field	Additional Changes
RL/info/*	info/*	Becomes Required.
RL/apiVersion	info/version	Becomes Required.
RL/info/termsOfServiceUrl	info/termsOfService	A free text field instead of URL.
RL/info/contact	info/contact/email
RL/info/description		Becomes non-mandatory.
RL/info/license	info/license/name	Becomes Required if License Object is used.
RL/info/licenseUrl	info/license/url
RL/swaggerVersion	swagger	Valid value changes to "2.0" only.
AD/basePath	host, basePath, schemes	The field is split into three fields, none of which is mandatory.
AD/models	definitions

TODO: add an elaborate explanation to the apis and operation migration. This is too complex for a table. **

What's New

• The Contact Object was added to the Info object for more elaborate contact information. It now contains an optional contact name and contact URL on top of the contact email.
• The License Object was added to the Info object to consolidate the license information.
• APIs are now served relative to the combination of host, basePath and schemes. They are defined at the root object and not per resource.
• Vendor Extensions - you now have the ability to add additional metadata at different sections of the schema. These extensions allow you to finely control your API description, should you need to share additional information that's not available by default with the current specification. The vendor extensions are available as part of the Paths (...).
• Operation grouping - In previous versions, the operations were grouped under a common resource. In this version, resources are being removed and replaced by tags. The paths of operations are listed at the top level of the document, and each operation can have one or more tags. These tags can be used to group the operations, and yes, operations can appear in more than one group. This allows you for far greater flexibility when it comes to grouping.
• Parameter declaration can now be performed at the path level. It will be applied to all operations declared on that path. The parameters MAY be overriden at the operation level but MAY NOT be removed by it.
• Models (schemas) now support maps via the additionalProperties property.
• Body parameters, models and responses support nested arrays.
• External documentation (including a description and a url) is now supported at various objects in the specification.
• responses now support a default description for all responses that are not implicitly declared.
• Headers can be described as part of the responses.

What's Changed

• Since Swagger 2.0 is now a single file (unless opted otherwise by the user), the name of the default hosted file has changes from /api-docs to swagger.json. There's no longer hierarchical directory structure.
• A swagger API documentation can no longer describe operations on different base paths. In 1.2 and earlier, each resource could have had a separate basePath. In 2.0, the basePath equivalents (schemes+host+basePath) are defined for the whole specification.
• The structure of most objects has changed (such as the Operation Object, the Parameter Object). Among other changes, in many cases instead of stating the type of the object, the property name directing to the object will state its type. For example, for operations, you would have a property name called "get" pointing to an Operation Object. As such, the method field is dropped from the object itself.
• Models can now only be used for "body" parameters. Other parameter types can only be of primitive types or array of primitive types.
• The name of the parameter type "form" was changed to "formData".
• The return value of an operation was moved to to the responses section, to be combined with the appropriate http status code (most likely in the 2XX range). As a result, the responses is now mandatory and must have at least one response described by it.
• void as a data type (only for Operation's return value) has been removed entirely. An operation that returns nothing will have no schema declaration for its response.
• Since the API version is now mandatory, it theoretically limits a single Swagger documentation to a single API version.
• The Resource Object was removed. Paths are now the base for describing operations on them and they are listed under the Swagger Object. Resources are replaced by Tags to allow a different form of Operation grouping.
• The API Object has been replaced with the Paths Object and Path Item Object.
• API Declaration's resourcePath was removed entirely.
• models is renamed to schemas and allows for much greater flexibility in declarations. A Schema Object can be used to declare primitives, arrays or models. It is now a subset of JSON Schema (with many additional fields compared to 1.2) and a few additional proprietary Swagger fields.
• The nickname field has been renamed operationId and is now not mandatory.
• The deprecated field type has changed to boolean.
• Operation's notes field was renamed to description.
• allowMultiple is replaced by collectionFormat to allow more flexibility in how multiple values are sent.
• responses now support primitives and arrays as a return value.

TODO:

• Add migration changes to security once the schema is available.