Implemented Ideas: Wizard to generate ObjectScript from an OpenAPI

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP 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. While for SOAP based APIs there is a special wizard in InterSystems IRIS that cuts down orchestrations development time, not all APIs used in integrations are SOAP. That's why @Jaime Lerga suggested to add a wizard similar to the SOAP wizard to generate a REST client from OpenAPI specification. Implementation of this idea cuts down the development time of the REST API orchestrations with InterSystems IRIS. This idea is one of most popular ideas on the InterSystems ideas. This article, the third in the "Implemented Ideas" series, focuses on the OpenAPI Suite solution developed by @Lorenzo Scalese.
 

In short, OpenAPI-Suite is a set of tools (packages and libraries), to generate ObjectScript code from an OpenAPI specification version 3.0. These tools allow to:  

• Generate server-side class.  
• Generate HTTP client classes.
• Generate client production (business services, business operation, business process, Ens.Request, Ens.Response) classes.
• A web interface to generate and download the code or generate and compile directly on the server.
• Convert specification from version 1.x, 2.x to version 3.0.

The scheme above provides the list of all packages developed in OpenAPI-Suite, and used libraries and web-services. Detailed description of each package and library, as well as other important details about solution are available in the series of articles written by the author of the implementation: OpenAPI Suite - Part 1 , OpenAPI Suite - Part 2

Special thanks to @Lorenzo Scalese for answering the questions about the implementation of this. Below is a short compilation based on his answers and articles dedicated to the OpenAPI-Suite application.

Scalese highlighted several reasons why he was intrigued by the implementation of this idea:

• He often found himself repeating the same tasks when designing REST APIs, both on the server and client sides. It was both time-consuming and inefficient.
• He noticed a gap in the field of API development - a lack of suitable tools for generating ObjectScript code from OpenAPI version 3 specifications.
• It is an extremely stimulating and professionally enriching technical challenge to design a code generator to address this issue.

During the implementation, the developer was impressed mostly by the ease with which he was able to generate ObjectScript classes. The use of the %Dictionary API proved to be an extremely valuable resource, greatly simplifying the process. Additionally, he was struck by the variety of expressions the OAS 3 specification allowed to achieve the same result. Managing this variability and ensuring coverage of all possible cases was one of the main challenges Scalese encountered.

The OpenAPI-Suite developer would like to make significant improvements to the user interface of the solution. Currently, it is rather basic and lacks customization options. Many features are only available in terminal mode, so he plans to add more advanced customization functionalities. Additionally, @Lorenzo Scalese is motivated to develop a full-fledged front-end application to enhance the user experience. Sometimes he also wonders whether creating a Swagger plugin for ObjectScript might not have been a better option, allowing direct generation of code accessible via https://editor.swagger.io/. This could enable more seamless integration into existing developer workflows.

The OpenAPI-Suite solution aroused great interest from InterSystems Developer Community members. It was installed 135 times using IPM, has 4 reviews from developers and has 5 stars rating. @Theo Stolker says in his review that OpenAPI-suite is the best possible option when the developer's goal is to generate client code for an API published as OpenAPI specification.

Please share your feedback about the highlighted solution and idea in the comments.

Don’t forget to post your ideas, vote and comment on existing ideas, implement Community Opportunity ideas!