Software AG Products 10.5 | Using CentraSite | Asset Management | Swagger to CentraSite REST API Mappings
 
Swagger to CentraSite REST API Mappings
This section describes how the Swagger objects and properties (as described in the Swagger specification) are mapped in the CentraSite REST data model. It shows the relationships between the Swagger root section, parameters, body fields, and their REST data model. It also lists the relationships between Swagger resources, methods, reference documentation, and security schemes, and how these values are mapped in REST API.
Note:
CentraSite supports Swagger version 2.0.
The following tables list the correspondences (mappings) between the fields of a RESTful API and Swagger document.
Swagger Root Section Fields
The Root section of the Swagger definition describes the basic information of a RESTful API, such as its title, external documents, security schemes and references.
Swagger Root Section Field
REST API Field
Notes
swagger
Currently, CentraSite does not support mapping the swagger version in the REST API's details page
title
Name
The title property is represented by the Name field in the REST API's details page.
description
Description
The description property is represented by the Description field in the REST API's details page.
termsOfServiceUrl
Currently, CentraSite does not support mapping the termsOfServiceUrlat the API level.
contact
Currently, CentraSite does not support mapping the contact property at the API level.
license
Currently, CentraSite does not support mapping the license property at the API level.
licenseUrl
Currently, CentraSite does not support mapping the licenseUrl at the API level.
externalDocs
The externalDocs are not explicitly mapped to the REST API; instead, the external documentation is attached as a file attribute to the Specification profile in the REST API details page.
host
Currently, CentraSite does not support mapping the host property at the API level.
basePath
Currently, CentraSite does not support mapping the basePath property at the API level.
schemes
The schemes are not explicitly mapped to the REST API; instead, the schemes (HTTP, HTTPS) are represented by the multiple base URLs in the Technical Details profile.
Note that CentraSite does not support mapping the WS and WSS schemes.
produces
Currently, CentraSite does not support mapping the produces property at the API level.
However, it is represented by the Response Content-Type field of a REST Method.
consumes
Currently, CentraSite does not support mapping the produces property at the consumes level.
However, it is represented by the Request Content-Type field of a REST Method.
paths
REST Resource
The paths property is represented by a collection of resources, wherein each of the resources have its path value mapped by the Name field of a REST Resource.
definitions
The definitions property is represented by the Request Schema or Response Schema field of a REST Method.
security
Currently, CentraSite does not support mapping the security at the API level.
However, it is represented by the Supported Access Token Types field in the API Portal Information profile.
Swagger Parameter Fields
The following tables show the mappings between various Swagger parameter types and attributes and how they are used by REST API. The mappings are grouped into tables for Swagger Parameter Types, and Swagger Parameter Attributes.
Swagger Parameter Types
Swagger Parameter Field
REST API Field
Notes
URI Parameter
Parameter of type, Path
The URI Parameter property is represented by the "Path" option in the Parameter Type field of a REST Parameter.
Query Parameter
Parameter of type, Query-String
The QueryParameter property is represented by the "Query-String" option in the Parameter Type field of a REST Parameter.
Header
Parameter of type, Header
The Header property is represented by the "Header" option in the Parameter Type field of a REST Parameter.
Form Parameter
Parameter of type, Form
The Form Parameter property is represented by the "Form" option in the Parameter Type field of a REST Parameter.
Body Parameter
Currently, CentraSite does not support mapping parameters of the type "Body".
However, a body parameter is represented by the Sample Request field of a REST Method.
Swagger Parameter Attributes
Swagger Attribute Field
REST API Field
Notes
name
Name
The Display Name property is represented by the Name field of a REST Parameter.
description
Description
The Description property is represented by the Description field of a REST Parameter.
in
The in property is represented by the Parameter Type field of a REST Parameter.
Currently, CentraSite does not support mapping parameters of the type "formData" and "body".
required
Required
The required property is represented by the Required field of a REST Parameter.
type
type=[string, number, boolean, array, file]
Data Type
The type property is represented by the Data Type field of a REST Parameter.
Currently, CentraSite does not support mapping parameters of the data type "file".
format
format=[int32, int64, float, double, byte, date, date-time, email, uuid]
Data Type
The format property is represented by the Data Type field of a REST Parameter.
Currently, CentraSite does not support mapping parameters of the data type "file".
items
Possible Values
The enum property is represented by the Possible Values field of a REST Parameter. Limitation: Currently, CentraSite supports the Possible Values field only for a "string" data type.
collectionFormat
Currently, CentraSite does not support the collectionFormat attribute.
default
Default Value
The default property is represented by the Default Value field of a REST Parameter.
maximum
Currently, CentraSite does not support the maximum attribute.
exclusivemaximum
Currently, CentraSite does not support the maximum attribute.
minimum
Currently, CentraSite does not support the minimum attribute.
exclusiveminimum
Currently, CentraSite does not support the minimum attribute.
minLength
Currently, CentraSite does not support the minLength attribute.
maxLength
Currently, CentraSite does not support the maxLength attribute.
enum
Possible Values
The enum property is represented by the Possible Values field of a REST Parameter.
pattern
Currently, CentraSite does not support the pattern attribute.
maxItems
Currently, CentraSite does not support the maxItems attribute.
minItems
Currently, CentraSite does not support the minItems attribute.
uniqueItems
Currently, CentraSite does not support the uniqueItems attribute.
multipleOf
Currently, CentraSite does not support the multipleOf attribute.
Swagger Resource Fields
Swagger resource properties (data) are mapped to the REST API resource fields. The following table shows the resource mappings between a Swagger definition and a REST API:
Swagger Resource Field
REST API Field
Notes
$ref
Currently, CentraSite does not support the $ref property.
However, the $ref property is represented by mapping the contained REST Resources and attaching the referenced files to the Specification profile in the API details page.
get, put,post,delete, options,head,patch
REST Method
The get property is represented as the REST Method object.
parameters
REST Parameter
The parameter property is represented as a REST Parameter object.
Swagger Method Fields
Swagger method properties (data) are mapped to the REST API method fields. The following table shows the resource mappings between a Swagger definition and a REST API:
Swagger Method Field
REST API Field
Notes
tags
Currently, CentraSite does not support the tags property.
summary
Name
The summary property is represented by the Name field of a REST Method.
description
Description
The description property is represented by the Description field of a REST Method.
externalDocs
The externalDocs are not explicitly mapped to the REST API; instead, the external documentation is attached as a file attribute to the Specification profile.
operationId
Currently, CentraSite does not support the operationId property.
security
Currently, CentraSite does not support mapping the security at the API level.
However, it is represented by the Supported Access Token Types field in the API Portal Information profile.
parameters
Parameter
The parameter property is represented by the Parameter field of a REST Method.
responses
Status Code
The responses property is represented by the Status Code field of a REST Method.
produces
Response Content-Type
The produces property is represented by the Response Content-Type field of a REST Method.
consumes
Request Content-Type
The consumes property is represented by the Request Content-Type field of a REST Method.
deprecated
Deprecated
The deprecated property is propagated to the taxonomy structure named Deprecated and represented by the API Maturity Status property defined in the API Portal Information profile.
Swagger Status Code Fields
Swagger status code properties (data) are mapped to the REST API status code fields. The following table shows the resource mappings between a Swagger definition and a REST API:
Swagger Method Field
REST API Field
Notes
code
Status Code
The HTTP status code property is represented by the Status Code field of a REST Method.
description
Description
The description property is represented by the Description field of a REST Method level.
schema
Currently, CentraSite does not support the schema property.
headers
Currently, CentraSite does not support the headers property.
examples
Currently, CentraSite does not support the examples property.
Swagger Security Scheme Fields
Swagger security schemes are not explicitly mapped to the REST API. Instead, the Swagger security schemes are propagated to the taxonomy structure named Security Types, and represented by the Supported Access Token Types property at the API Portal Information profile.
Security Type
Description
API Key
The API's authentication requires using an API key.
Basic Authentication
The API's authentication requires using Basic Access Authentication as described in RFC2617.
Digest Authentication
The API's authentication requires using Digest Access Authentication as described in RFC2617.
OAuth 1.0
The API's authentication requires using OAuth 1.0 as described in RFC5849.
OAuth 2.0
The API's authentication requires using OAuth 2.0 as described in RFC6749.
x-{other}
The API's authentication requires using another authentication method.
The supported security schemes along with their scheme reference name are mapped in the CentraSite registry. For more information about the security scheme, see the Swagger specification.