Skip to content

Instantly share code, notes, and snippets.

@jakul

jakul/open_api_v3_changes.md

Created August 3, 2017 10:40
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save jakul/619bf887300af41efa1623c33f3288ef to your computer and use it in GitHub Desktop.
Save jakul/619bf887300af41efa1623c33f3288ef to your computer and use it in GitHub Desktop.
Download ZIP
Description of the main changes between Open API V2 and V3
Raw
open_api_v3_changes.md
  • New explicit versioning schema
  • Recommend swagger.json/swagger.yaml are now called openapi.json/openapi.yaml
  • Switch from Github Flavoured Markdown syntax to CommonMark syntax
  • New top-level construct Components holds a set of objects to be reused throught the rest of the API. This allows us to define re-used things in one place and reference them, instead of repeating them. Will be especially useful for error responses, pagination parameters, etc
  • New info.servers construct replaces basePath. This may allow us to combine all of our separate Open API specs into one, mega spec.
  • Ability to specify a path parameter at the top level (i.e. no need to duplicate the definition of {policy_uuid} for the GET, PATCH, PUT and DELETE endpoints)
  • Moving of request BODY parameters into their own part of the path definition
  • Support for different request BODY definitions based on the Content-Type of the request (e.g. we could make one API support both JSON and YAML)
  • Support for different responses based on Content-Type
  • Now able to send paramters to the API in cookies
  • Now able to mark endpoints/parameters as deprecated
  • Now able to mark querystring parameters as allowed to have empty values
  • Can specify that multiple received copies of a parameter should be treated a a list or exploded into muliple parameters
  • Parameters can have examples
  • Various other parameter changes to allow more detailed specification of how they are serialised
  • File uploads can now describe the endcoding they require (binary/base64)
  • Multi-part form uploads must now have explicitly defined input parameters
  • Response codes must be strings (e.g. '200' not 200)
  • Response codes can be defined for ranges (e.g. 1XX, 2XX, 3XX, 4XX or 5XX)
  • Response specifications can now specify static links, which are urls with templated parameters based on the response. This means that we don't have to include dynamic _links within the response body anymore, reducing the payload size and preventing duplication on fetch endpoints.
  • Capability to send null as a parameter value
  • Schema composition, inheritance and polymorphism. This will allow us to make generic endpoints which validate the request based on parameters in the request (e.g. make Connexion validate that the data part of a request is valid against the schema uuid defined in the request). The discriminator in the request allows valiation against different schemas.
  • Support for bearer tokens as an API security format (i.e. JWT)

Links:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment