View Categories

Swagger & Data Model

3 min read

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:

  • Available endpoints and operations on each endpoint eg GET , POST
  • Operation parameters Input and output for each operation
  • Authentication methods
  • Contact information, license, terms of use and other information.

API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines. 

Data Models (Schemas) #

OpenAPI 3.0 data types are based on an extended subset JSON Schema Specification Wright Draft 00 (aka Draft 5). The data types are described using a Schema object. 

Schema Object #

The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00.For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema.

Properties #

The following properties are taken directly from the JSON Schema definition and follow the same specifications:

  • title
  • multipleOf
  • maximum
  • exclusiveMaximum
  • minimum
  • exclusiveMinimum
  • maxLength
  • minLength
  • pattern (This string SHOULD be a valid regular expression, according to the Ecma-262 Edition 5.1 regular expression dialect)
  • maxItems
  • minItems
  • uniqueItems
  • maxProperties
  • minProperties
  • required
  • enum

The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.

  • type – Value MUST be a string. Multiple types via an array are not supported.
  • allOf – Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
  • oneOf – Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
  • anyOf – Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
  • not – Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
  • items – Value MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
  • properties – Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
  • additionalProperties – Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. Consistent with JSON Schema, additionalProperties defaults to true.
  • description – CommonMark syntax MAY be used for rich text representation.
  • format – See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
  • default – The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.

Platform allows you both bottom up and top down approach. You can define the Specification first and upload the same to create the api or create the integration flow and extract the open api specification from the same.

Platform has the option for defining the Data Model which then can be used in api specification.

What are your Feelings