Open API spec 2.0 vs 3.0

Hello Developers,

This post is to shed light on major differences between open api spec 2.0 and 3.0. Knowing the major non compatible differences will help migrating from 2.0 spec to 3.0 spec.

1. Version
How to know whether the api definition is adhering to 2.0 spec or 3.0 spec ?
In 2.0 spec there is a property called “swagger” which tells you the version of spec, for example

"swagger": "2.0"

3.0
This is replaced with new property “openapi” and it should be used as below,

"openapi": "3.0.0"

2. Multiple Servers
Open API spec 2.0 has placeholder only for one host or one server details and doesn’t have support to have multiple server information. This drawback is taken care in 3.0 spec, so now there is new servers object array where you can have host information with any variable placeholders in the host url as well.
Example :

"servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]

In the above example url has username, port and basepath as variable fields ( placeholders ), which are described in variables object section and also default values can be provided for each of them.
Rendering of this multiple server details in swagger ui is shown below,

3. Components
Open API spec 3.0 provides components object which can contain schemas, parameters, responses, examples, security schemes, links, request bodies, headers and callbacks. This component object won’t affect the API untill it is referenced somewhere in the API.
Advantage : If multiple operations of an API needs similar input structure the the input structure can be defined under component as request bodies and can be reused in multiple paths. Similarly headers, responses and so on can be reused.

"components": {
  "schemas": {
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  }
}

4. Security Definitions
2.0

"securityDefinitions": {
    "Oauth2_ClientCredentials": {
        "type":"oauth2",
        "tokenUrl":"http://swagger.io/api/oauth/dialog",
        "flow":"client_credentials",
        "scopes":""
    }
}

3.0

"components": {
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "http://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}

Applying the security on operations or globally for all resources in the definition remains same.

"security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]

Please comment if any clarifications or questions, I will try to get back with proper answer.
Thank you.