Skip to content

Latest commit

 

History

History
226 lines (154 loc) · 8.78 KB

1.0.0.md

File metadata and controls

226 lines (154 loc) · 8.78 KB

Specification of SWSG extensions for OpenAPI

Version 1.0.0

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

Introduction

This documents defines extensions to the OpenAPI Specification (OAS) version 3.0.1 in order to support web services generation through SWSG. It introduces new schemas, and modify existing schemas (only to add new properties) in the way allowed in the Specification Extensions section of the OAS.

Table of Contents

Specification

Data Types

SWSG uses a different type system from OpenAPI. Some fields in the following new schemas require a string or an object that MUST be a valid SWSG type. SWSG types can be scalar (strings) or parameterized types (objects).

Scalar Types

  • Str
  • Boolean
  • Integer
  • Float
  • Date
  • DateTime

Parametrized Types

EntityRef

Designates a reusable Schema defined in the Component Object.

It has the following parameters:

Name Type Description
entity string The name of a reusable Schema in the Component Object.

Example:

type:
  entity: User
SeqOf

Designates a sequence (or list) of a given type.

It has the following parameters:

Name Type Description
seqOf Type The type of every item of the sequence.

Example:

type:
  seqOf: User
OptionOf

Designates the optional version of a given type.

It has the following parameters:

Name Type Description
optionOf Type The type to make optional.

Example:

type:
  optionOf: User

Modified Schemas

OpenAPI Object

Added Fields
Field Name Type Description
x-swsg-version string REQUIRED. This string MUST be the semantic version number of the SWSG extensions that the OpenAPI document uses. The x-swsg-version field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string.

Components Object

Added Fields
Field Name Type Description
x-swsg-ac [Atomic Component Object] A collection to hold reusable Atomic Component Objects.
x-swsg-cc [Composite Component Object] A collection to hold reusable Composite Component Objects.

Operation Object

Added Fields
Field Name Type Description
x-swsg-ci Component Instance Object An instance of the component in charge of serving this service.

RequestBody Object

Added Fields
Field Name Type Description
x-swsg-name string REQUIRED. The name of a variable from which the body contents should be accessible.

New Schemas

Atomic Component Object

Describes a unit of computation. An atomic component is executed in a given context (which can be seen as a set of variables). It MAY change this context by adding or removing variables, or stop execution by returning an HTTP response. Atomic Components MUST be provided with an implementation.

Fixed Fields
Field Name Type Description
name string REQUIRED. The name of the component. It MUST be unique and SHOULD begin with a capital letter.
params [Variable Object] A set of variables that MAY be used in the component's implementation and MUST be specified when the component is instanciated. These variable are not in the execution context because their values are known at compile-time.
pre [Variable Object] A set of variables that are required in the execution context by this component.
add [Variable Object] A set of variables that will be added to the execution context by this component.
rem [Variable Object] A set of variables that will be removed from the execution context by this component.

Composite Component Object

Allows to use several other components (atomic or composite) at once.

Fixed Fields
Field Name Type Description
name string REQUIRED. The name of the component. It MUST be unique and SHOULD begin with a capital letter.
params [Variable Object] A set of variables that MAY be used in the component's implementation and MUST be specified when the component is instanciated. These variable are not in the execution context because their values are known at compile-time.
components [Component Instance Object] REQUIRED. An ordered list of Component Instance Objects that this composite component will sequentially call when instanciated.

Component Instance Object

Describes a reference to a component along with the necessary information to use it concrectly (like arguments).

Fixed Fields
Field Name Type Description
component string REQUIRED. The name of the component to instanciate.
bindings [Binding Object] A set of Binding Objects that gives arguments to each parameter of the component.
aliases [Alias Object] A set of Alias Objects that allow to dynamically rename variables defined in the pre, add or rem fields of the component.

Binding Object

Associates a component parameter to a value.

Fixed Fields
Field Name Type Description
param Variable Object REQUIRED. The variable defined in the params set of the component.
argument Variable Object or Constant Object REQUIRED. A value to associate to the parameter. If this is a Variable Object, this means that the actual value is the one that will be given to the parent component parameter designated by the variable. If this is a Constant Object, the value is given as a literal.

Alias Object

Associates a variable name to a new name. This is used to rename variables when instanciating a component.

Fixed Fields
Field Name Type Description
source string REQUIRED. The name of a variable present in the component definition.
target string REQUIRED. The new name to give to this variable (only in the current instance of the component).

Variable Object

Describes a variable: a name and a type.

Fixed Fields
Field Name Type Description
name string REQUIRED. The name of the variable.
type Type REQUIRED. This MUST be a valid type, as defined in the Data Types section.

Constant Object

Describes a literal value associated to a variable.

Fixed Fields
Field Name Type Description
type Type REQUIRED. This MUST be a valid type, as defined in the Data Types section.
value string REQUIRED. This MUST be parsable as the type given in the type field.