Powerful IDE for API-first design, documentation and development.

Start my Free Trial

This article describes how you can convert your Swagger 2.0 API specifications into RAPID-ML using the Swagger Importer in RepreZen API Studio


The main purpose of the Swagger Importer is to give Swagger developers who wish to try out RAPID-ML a head start. The Swagger and RAPID languages are not identical, so you cannot expect a straight translation of all the features in your Swagger API. Some Swagger features are not directly supported in RAPID-ML, others are translated differently, and RAPID-ML has features that Swagger does not. This means two things: 

  1. The imported RAPID-ML model will need some manual adjustment.
  2. Existing clients for an API defined in Swagger will need tweaking in order to work with a RAPID-ML API that was imported from that same Swagger spec.

Over time, you can expect RAPID-ML to evolve towards greater alignment with Swagger, so the import process will be more complete and straightforward.


Using the Swagger Importer


You can access the Swagger Importer as follows:

  1. Open the API Studio Import Wizard:

  2. Select Import Swagger and click Next >

  3. Select the Swagger file you wish to import, either from the file system, a URL or from the workspace, and click Finish.

  4. The RAPID-ML version of the selected Swagger spec will then open in the RAPID-ML editor.


The following sections detail how the Swagger Importer works so that you will understand the resulting RAPID-ML code.


Data Types for Requests and Responses


Swagger 2.0 uses JSON schema to define request and response data. This is translated into RAPID-ML data structures - simple, technology-neutral, data type definitions from which message schemas may be generated. The message format and details of generated schema will depend on the media type(s) supported by the API and the way in which the data types are realized in the RAPID-ML resource definitions.


The Swagger Importer looks at each request and response defined in Swagger and, if it finds an associated schema, it traverses the data type graph transitively from the root type generating RAPID-ML data structures for each type it discovers. This means that only those data types reachable in this way will be added to the canonical data model generated by the importer. Referenced schema definitions will be re-used if possible.  But if the schema is defined in-place, new definitions will be created each time.


The root data type will then become the type bound to the request or response in question. For example:  

// Swagger
"get" : {
  "tags" : [ "PathObject" ],
  "description" : "",
  "operationId" : "getPath",
  "responses" : {
    "200" : {
      "description" : "",
      "schema" : {
        "$ref" : "#/definitions/PathObject"
      }
    }
  }
}

// RAPID-ML
method GET getPath
request
response type PathObject statusCode 200


If a Swagger request has body or form parameters, these will converted into a new RAPID data structures named 'bodyParameter[sequence-number]' or 'formParameter[sequence-number]', which is bound to the request. For example: 

method POST
request type bodyParameter3


Data Types for Resources


Unlike Swagger, RAPID-ML resource definitions also have a data type - they are each bound to a RAPID data structure. The data type for each RAPID resource must therefore be inferred during the import process. The algorithm for each resource is:

  • Make a list of data types bound to responses on each operation (e.g, GET, POST, PATCH) 
  • Choose the resource data type using the following logic:
    GET > any other HTTP operation, then 200 > all ‘successes’ (201-300) > any other response

If a data type cannot be deduced then a void type is added to the RAPID-ML data model and used. For example:

objectResource articles type _rapid_void

These, then, become flags in the RAPID code, indicating that human intelligence is required to determine, or create, the data type to which the resource should be bound.


Duplicate Data Structures


The Swagger importer makes no attempt to spot duplicate data structures, and will simply add alphanumeric suffixes to structures with the same name that are found during the transitive discovery process. For example:

  

structure SegmentObject
id : string
pointA : reference PointA1
pointB : reference PointB1
structure PointA1
x : integer
y : integer
structure PointB1
x : integer
y : integer
structure TriangleObject
id : string
pointA : reference PointA2
pointB : reference PointB2
pointC : reference PointC

  

In the above case we can clearly see that types PointA1 and PointB1 are identical in terms of properties. This data model can therefore be manually refactored by replacing these PointA1 and PointB1 with a structure called Point that is used for reference properties pointA and pointB in SegmentObject. 


Data Types for Template, Header and Query Parameters


The rules for template, header and query parameters are as follows: 

  • All parameters are assumed to be primitives.
  • Parameters from enumerations are not supported.
  • Array parameters will be interpreted as a single string parameter in RAPID-ML. 
  • An attempt will be made to bind template parameters to one of the properties of the structure bound to the resource. For example: if we have inferred that the resource type is Pet, and Pet has property id, and the resource has template parameter id, {id} will be bound to Pet#id.