Open API 3.0 support in Rational Software Architect Designer and Rational Software Architect Designer for WebSphere Software

OpenAPI 3.0 support in Rational Software Architect Designer/Rational Software Architect Designer for WebSphere Software

Introduction

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

Refer to below links for more details about OpenAPI specification:

https://swagger.io/specification/

https://swagger.io/docs/specification/about/

Since Rational Software Architect Designer 9.7.1 and Rational Software Architect Designer for WebSphere Software 9.7.1, support for modeling and generation of OpenAPI 3.0 specification based Representational State Transfer (REST) web services is provided.

Palette tools, template models, and profiles to model RESTful web services are enhanced to support OpenAPI3.0-specific capabilities.

Creating REST models by using template models

By using the Representational State Transfer (REST) or OpenAPI template models, you can create a UML model that has the corresponding profile applied and reference library elements imported so that you can model REST web service elements and OpenAPI elements etc.

Before you begin

To model Rest web services, you must have the REST Modeling capability enabled. To model OpenAPI capabilities by using stereotypes in the OpenAPI, you must have the OpenAPI Modeling capability enabled.

Procedure

1. Click File > New > Model.
2. On the Create Model page, click Standard template; then click Next.
3. On the next Create Model page, in the Categories pane, click REST Modeling, and in the Templates pane, complete one of the following steps:
   • To create a OpenAPI3 REST Model, click REST Service Model (OpenAPI3). If you select this option, the generated model has both REST and OpenAPI3 profiles applied and also it imports the OpenAPI3 reference library.
     Tip: If these templates are not displayed, select the Show All Templates check box.
4. In the File name field, type a name for the model and browse to a destination folder.
5. Click Finish.

Results

The new model is created and displayed in the Project Explorer view. The new model and its default diagram are opened for editing. You can now model REST web service model elements or OpenAPI3 elements.

Modeling OpenAPI3 elements

You can now update OpenAPI3 REST Service model by using the OpenAPI Specification (formerly known as the Swagger Specification) version 3.0 elements that are available in the Palette under OpenAPI3 drawer.

For example, add the REST Application and Resources elements as required.

Below sections explain the steps for modeling i) Global Parameters and Global Responses and ii) Inline Schemas.

Procedure

1. Modeling Global Parameters and Global Responses
   1. Creation of Global Parameters and Global Responses
      1. Select OpenAPI Application Class from OpenAPI3 palette and drop on to the UML diagram.
      2. OpenAPI3 application class element is added to the model.
      3. Newly added class element has Globals as the default UML Operation.
      4. Adding Global responses:
         1. Select OpenAPI Response Parameter from OpenAPI3 palette and add to the Globals operation.
         2. Ensure that the other details of OpenAPI response parameter are set as needed.
      5. Adding Global parameters:
         1. Select OpenAPI Parameter from the OpenAPI3 palette and add to the Globals operation.
         2. Ensure that the other details of OpenAPI parameter are set as needed.
   2. Referencing Global parameter and Response from Resource operations
      1. Select OpenAPI Parameter or OpenAPI Response Parameter from OpenAPI3 palette.
      2. While adding OpenAPI Parameter or OpenAPI Response Parameter to a Resource operation, options to select an existing element or to create a new element appears.
      3. Select the Select Existing element option to open a Select Element dialog box.
      4. Select the global response or parameter and click OK.
2. Modeling the Inline schemas

1. 1. Select the OpenAPI Parameter or OpenAPI Response Object element in Project Explorer
   2. Open the Properties view.
   3. Ensure that the type is set to the corresponding schema definition class.
   4. Open the REST tab and enable the Inline Schema option.

Transforming REST models and REST service elements

You can transform a UML model that has both Representational State Transfer (REST) profile and OpenAPI3 profile applied into corresponding OpenAPI3 artifact and vice versa.

Transforming REST or OpenAPI3 models into OpenAPI3

To transform a REST service model into OpenAPI3, configure a REST Service Model to OpenAPI 3.0 transformation, and then run the transformation.

Before you begin

You must be in the Modeling perspective and the REST Modeling capability must be enabled.

Procedure

Note: A OpenAPI3 file that is compliant with OpenAPI Specification version 3.0 is generated.

Transforming OpenAPI3 into elements in UML models

To transform OpenAPI3 into a UML model with the corresponding stereotypes applied, configure a OpenAPI 3.0 to REST Service Model transformation and then run the transformation.

Before you begin

You must be in the Modeling perspective and the REST Modeling capability must be enabled.

Procedure

1. To create a model project and a model from the REST Service Model (OpenAPI3) template, complete the following steps:
   1. Click File > New > Model Project, and complete the pages in the Model Project wizard.
   2. On the Create Model page of the wizard, in the Categories pane, click REST Modeling, then in the Templates pane, click REST Service Model (OpenAPI3).
   3. Optional: Complete the remaining pages in the wizard.
   4. Click Finish. The modeling project is displayed in the Project Explorer view and the REST and OpenAPI3 profiles are applied to the model.
2. Create a OpenAPI 3.0 to REST Service Model transformation configuration:
   Click File > New > Transformation Configuration, select OpenAPI 3.0 to REST Service Model under Service Oriented Architecture Transformations category, and complete the steps in the wizard. Specify the following values in the transformation configuration file:
   1. On the Source and Target Page, select the OpenAPI3 input file as source and select the model that is created as target.
      Note: The OpenAPI3 input file must be compliant with the OpenAPI Specification version 3.0.
   2. Optional: Specify additional properties that are unique to the OpenAPI3 to REST model transformation:

1. Click File > Save.
2. In the Transformation configuration editor, click Run to run the transformation. The transformation is run and a model is generated from the source OpenAPI3 file.

The OpenAPI3 profile contains stereotypes that you can apply to model Representational State Transfer (REST) elements such as application, resource classes, and resource methods.

To use these stereotypes, the OpenAPI3 profile must be applied to your UML model. If you use the stereotypes in the OpenAPI3 profile, you must also apply the REST profile to the model; the OpenAPI3 stereotypes and type library extend the REST profile and type library.

The following table lists the stereotypes that you can apply to elements in a model on which the OpenAPI3 profile is applied. In some cases since the OpenAPI3 stereotypes extend REST stereotypes, the REST stereotype must also be applied with it.

Migration of Swagger 2.0 YAML/JSON artifacts to OpenAPI 3.0

By using the Swagger 2.0 to OpenAPI 3.0 migration utility, you can migrate the existing Swagger 2.0 YAML/JSON artifacts to corresponding OpenAPI 3.0 YAML/JSON artifacts.

Before you begin

You must be in the Modeling perspective and the REST Modeling capability must be enabled.

Procedure

1. Right click on the Swagger 2.0 YAML/JSON file and click Generate OpenAPI 3.0.
2. In the Swagger to OpenAPI convertor wizard, specify the Target file name and Target file format.
3. Click on Finish.