OpenAPI Support

OpenAPI

The OpenAPI Specification (OAS) is an industry standard for specifying and documenting web service APIs. OpenAPI specifications are JSON or YAML documents with a fairly complex structure, more complicated and more powerful than that of WADL.

Importing OpenAPI as Website

Hyperlyn has partial support for the latest version of the specification — Version 3.0.3 published on 20 February 2020. You can import JSON-formatted OpenAPI documents into Hyperlyn projects as Websites.

OpenAPI Object

• openapi — Ignored
• info — Ignored
• servers — A Website and a hierarchy of Resources are generated from the URL of the first server in the list, with default variable values plugged in.
• paths — Points to a Paths object.
• components — Points to a Components object.
• security — Ignored
• tags — Ignored
• externalDocs — Ignored

Components Object

• schemas — Map of names to Schema objects.
• responses — Ignored
• parameters — Map of names to Parameter objects.
• examples — Ignored
• requestBodies — To be implemented
• headers — To be implemented
• securitySchemes — Ignored
• links — Ignored
• callbacks — Ignored

Paths Object

• /{path} — Each field points to a PathItem object.

PathItem Object

Generates a hierarchical set of Resources.

• $ref — Ignored
• summary — Ignored
• description — Ignored
• get — Points to an Operation object.
• put — Points to an Operation object.
• post — Points to an Operation object.
• delete — Points to an Operation object.
• options — Points to an Operation object.
• head — Points to an Operation object.
• patch — Points to an Operation object.
• trace — Points to an Operation object.
• servers — Ignored
• parameters — Array of Parameter objects that are processed and attached to the last Resource generated from this PathItem (see below).

Operation Object

This object is parsed into one or more Request Templates.

If there are one or more Media Type objects defined under requestBody/content, a template with payload is generated for each one. If not, a single template without payload is generated from this operation.

• tags — Tags attached to the Request Template.
• summary — Ignored
• description — Ignored
• externalDocs — Ignored
• operationId — Ignored
• parameters — Array of Parameter objects that are processed and attached to all Request Templates generated from this Operation.
• requestBody — Points to a Request Body object.
• responses — Ignored
• callbacks — Ignored
• deprecated — Ignored
• security — Ignored
• servers — Ignored

Parameter Object

This object is parsed into a Parameter and attached to a Resource or Request Template.

• $ref — If this parameter is present, it is treated as an internal reference to an actual definition in the components/parameters section. External references are not supported.
• name — The name of the parameter
• in — Used to determine the location of the parameter: Path, Header, Cookie, Query.
• description — Ignored
• required — If this flag is set, then the parameter option If value is empty will be set to Error.
• deprecated — Ignored
• allowEmptyValue — If this flag is set, then the parameter option If value is empty will be set to Leave.
• style — To be implemented
• explode — To be implemented
• allowReserved — Ignored
• schema — Points to a Schema object — Default values are extracted from schema.
• example — Ignored
• examples — Ignored
• content — Ignored

Request Body Object

• $ref — To be implemented
• description — Ignored
• content — A map from media type strings to Media Type objects.
• required — Ignored

Media Type Object

This object is parsed into a single Request Template with payload.

• schema — Payload type and default value is extracted from schema.
• example — Ignored
• examples — Ignored
• encoding — Extra information for multipart/form-data parameters: content type, content disposition and other headers.

The media type name is obtained from the content map in the Request Body object. It determines the type of payload as follows

• application/x-www-form-urlencoded — A Multipart Form Data payload is generated. The schema field below is expected to define an object. Its fields define the multipart parameters.
• multipart/form-data — A URL Encoded payload is generated. The schema field below is expected to define an object. Its fields define the URL encoded parameters.
• Otherwise, a text or binary payload is generated, depending on the type defined in the schema field.
  • If the schema defines a string type with binary or base64 format, the payload is binary.
  • Otherwise, the payload is a text payload.

Header Object

Parsed into a Parameter with the location field set to Header.

• $ref — To be implemented

Schema Object

• $ref — If this parameter is present, it is treated as an internal reference to an actual definition in the components/schemas section. External references are not supported.
• default — Provides a default value for the parameter/payload.
  • A recursive default value is computed for objects and arrays without default values, if they have component types with default values.

Encoding Object

• contentType — Used to provide a media type and encoding for Multipart Form Data parameters.
• headers — Map of header names to Header objects.
  • Used to provide custom headers for Multipart Form Data parameters.
  • Content-Type headers are ignored.
  • Content-Disposition headers are parsed and their name and filename fields are displayed in the UI.
• style — To be implemented
• explode — To be implemented
• allowReserved — Ignored

Last updated on 2023-12-05