Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
The OpenAPI importer imports OpenAPI 2.0 Specification service descriptors encoded in YAML (Swagger) into a OpenAPI connector.
Find here how OpenAPI entities are mapped to data model elements in the Implementation folder.
Basic Building Blocks of a REST Service
An OpenAPI document is simply a set of nested definitions. The grammar is as follows:
Code Block |
---|
basePath: /support consumes: - application/json - text/xml definitions: SupportCase: properties: id: type: string customerID: type: string customerName: type: string date: format: date-time type: string shortDescription: type: string status: type: string RESTError: properties: message: type: string SupportCaseInfo: properties: supportCaseCount: type: integer customers: items: $ref: '#/definitions/String' type: array ListOfSupportCases: properties: supportCases: items: $ref: '#/definitions/SupportCase' type: array ResolveMessage: properties: message: type: string info: description: |- ###Manage support cases. This REST service provides you with a simple support manager. You can create, resolve and close support cases, and get support case information. - Please provide a valid API token to access all methods. - Additionally provide valid user credentials to access DELETE or PUT. title: SupportAPI version: 1.0 paths: /supportcases: get: description: Get some general info on existing support cases (number, affected customers). responses: '200': description: '' schema: $ref: '#/definitions/SupportCaseInfo' default: description: |- - 400 - Logical error, Bad Request - 404 - Technical error, Not Found - 500 - Technical error (See message string for error details.) schema: $ref: '#/definitions/RESTError' summary: Get some general info on existing support cases (number, affected customers). tags: - Support Case Info post: description: Create a new support case. parameters: - in: body name: supportCase required: true schema: $ref: '#/definitions/SupportCase' responses: '201': description: '' schema: $ref: '#/definitions/SupportCase' default: [...] schema: $ref: '#/definitions/RESTError' summary: Create a new support case. tags: - Create a New Support Case /supportcases/: [...] /supportcases/{id}: [...] /supportcases/{id}/resolve: [...] /supportcases/customer/{customerID}/: [...] produces: - application/json - text/xml security: - basic: [] - API-Key: [] securityDefinitions: basic: description: Authenticate using HTTP Basic Authentication type: basic API-Key: description: Authenticate using pre-acquired API key in: header name: API-Key type: apiKey swagger: '2.0' tags: - description: Create a new support case. name: Create a New Support Case - description: Get information on support cases. name: Support Case Info - description: Transition a support case to a new state. name: Transition Support Case |
When importing an OpenAPI description, the importer will generate a package structure from the OpenAPI definitions. The definitions
section corresponds to the Types package, the paths
section corresponds to the Services package within the imported service.
List of Supported REST Service Elements And Rules
Services are defined using the following elements:
by
Connector
swagger
info
title
description
host
basePath
schemes
A list of transfer protocols of the API. The first scheme is set as protocol in the REST alias.
Info |
---|
The REST adapter only supports HTTP and HTTPS. |
consumes
A list of MIME types the APIs can consume.
Info |
---|
The REST adapter only parses JSON and XML. |
produces
A list of MIME types the APIs can produce.
Info |
---|
The REST adapter only parses JSON and XML . |
paths
$ref
methods
tags
summary
description
externalDocs
operationId
consumes
.
produces
parameters
responses
description
schema
A definition or definition reference of the response structure.
Info |
---|
The adapter does not support primitives as response therefore a responses of these types are ignored. |
headers
examples
schemes
deprecated
security
parameters
definitions
parameters
responses
securityDefinitions
security
tags
name
description
externalDocs
externalDocs
Rp | |
---|---|
|