Introduction

A REST API (Representational State Transfer) is an interface that allows different applications to communicate with each other through the HTTP protocol, using standard operations such as GET, POST, PUT, and DELETE. REST APIs are widely used in software development to expose services accessible by other applications, enabling integration between different systems.

However, to ensure that APIs are easy to understand and use, good documentation is essential. This is where OpenAPI comes in.

OpenAPI is a standard for describing RESTful APIs. It allows for a structured definition of an API's functionality, specifying available endpoints, accepted and returned data types, required parameters, and expected responses. All this information is collected in a specification file (usually with a .yaml or .json extension), which can be interpreted by automated tools to generate code, documentation, and more.

The OpenAPI Specification is designed to be readable by both machines and humans, enabling the description, production, consumption, and visualization of RESTful web services in a standardized way. Therefore, an OpenAPI document represents a formal description of the API, useful both for developers who need to use it and for tools that can leverage it to automate various processes.

Why is it useful to define a specification file?

Adopting OpenAPI to document an API offers several benefits:

• Clarity: It provides detailed and structured documentation, allowing developers to quickly understand how to interact with the API, what requests to send, and what data to expect in response.
• Automation: Documentation can be automatically generated from the code, staying up-to-date with any API changes.
• Interactivity: Tools like Swagger, an open-source suite for API documentation and testing, include Swagger UI. This allows you to explore and test APIs directly from the browser, simplifying development, verification, and understanding of APIs.
• Standardization: Using OpenAPI ensures that documentation follows a shared, recognized format, facilitating integration with other tools and services.

How can you produce an OpenAPI document?

There are two main approaches to generate an OpenAPI specification file:

• "Code-first" (automatic) approach: If a REST API has already been developed in InterSystems IRIS, you can automatically generate the OpenAPI documentation without manually writing the specification file. IRIS offers an integrated feature to export the OpenAPI documentation in JSON or YAML format, based on the REST class definitions.
• "Specification-first" (manual) approach: In this case, the OpenAPI file is manually written in YAML or JSON, describing all the endpoints, parameters, and expected responses. This approach is useful when you want to define the API before implementing it, facilitating design and sharing with other developers or stakeholders.

Automatic Approach

There are two ways to automatically generate the OpenAPI specification file in InterSystems IRIS.

Method 1: Using the GetWebRESTApplication Function

One approach is to use the GetWebRESTApplication function provided by the %REST.API class.
A practical example of how to use it is by adding the following function in the dispatch class:

ClassMethod GenerateOpenAPI() As %Status
{
    // The name of the REST application
    Set webApplication = "MyAPP"  // Replace with the name of your web app
    // Retrieve the OpenAPI 2.0 documentation
    Set sc = ##class(%REST.API).GetWebRESTApplication("", webApplication, .swagger)
    
    If $$$ISERR(sc) {
        Quit sc  // If an error occurred, exit the method
    }
    
    // Return the documentation in JSON format
    Set %response.ContentType = "application/json"
    Do ##class(OMRREST.impl).%WriteResponse(swagger.%ToJSON()) 

    Quit $$$OK
}

Additionally, add the following route to the UrlMap:

  <Route Url="/openapi" Method="GET" Call="GenerateOpenAPI"/>

At this point, you'll have everything you need to generate the specification file from your dispatch class. To view the documentation, connect to the URL shown (where MyWebapp is the name of your web application, as defined in the management portal):

<host>:<port>/MyWebapp/openapi

The JSON generated this way represents the OpenAPI specification of your API. After exploring the second method, we will see how to view and test it in Swagger.

Method 2: Using the Management API

Another way to generate the OpenAPI specification file is by using the InterSystems IRIS Management API.

To call this service, you can use tools like Postman, which is a developer tool that allows you to test, document, and automate APIs.
Postman provides a simple and intuitive interface for sending HTTP requests (GET, POST, PUT, DELETE, etc.), viewing responses, managing authentication, and creating automated tests.

To make the request using Postman, follow these steps:

1. Click on the New button and create an HTTP request.
2. Configure the request as follows and send it:
   • Select GET as the HTTP method.
   • Specify the URL in the following format, using the <baseURL> of your instance:

     https://<baseURL>/api/mgmnt/v1/namespace/myapp

     Here, namespace is the name of the namespace where you have created the REST service, and myapp is the name of your web application.
   • Set the Authorization method to Basic Auth and provide the username and password of a user with read access to the specified namespace.

Once the JSON is generated, it can be viewed and tested using tools like Swagger Editor.

{
   "info":{
      "title":"",
      "description":"",
      "version":"",
      "x-ISC_Namespace":"MyNamespace"
   },
   "basePath":"/MyWebapp",
   "paths":{
      "/loginForm":{
         "post":{
            "parameters":[
               {
                  "name":"payloadBody",
                  "in":"body",
                  "description":"Request body contents",
                  "required":false,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "operationId":"loginForm",
            "x-ISC_ServiceMethod":"loginForm",
            "responses":{
               "default":{
                  "description":"(Unexpected Error)"
               },
               "200":{
                  "description":"(Expected Result)"
               }
            }
         }
      },
      "/refresh":{
         "post":{
            "parameters":[
               {
                  "name":"payloadBody",
                  "in":"body",
                  "description":"Request body contents",
                  "required":false,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "operationId":"refresh",
            "x-ISC_ServiceMethod":"refresh",
            "responses":{
               "default":{
                  "description":"(Unexpected Error)"
               },
               "200":{
                  "description":"(Expected Result)"
               }
            }
         }
      },
      "/logout":{
         "post":{
            "parameters":[
               {
                  "name":"payloadBody",
                  "in":"body",
                  "description":"Request body contents",
                  "required":false,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "operationId":"logout",
            "x-ISC_ServiceMethod":"logout",
            "responses":{
               "default":{
                  "description":"(Unexpected Error)"
               },
               "200":{
                  "description":"(Expected Result)"
               }
            }
         }
      },
      "/openapi":{
         "get":{
            "operationId":"GenerateOpenAPI",
            "x-ISC_ServiceMethod":"GenerateOpenAPI",
            "responses":{
               "default":{
                  "description":"(Unexpected Error)"
               },
               "200":{
                  "description":"(Expected Result)"
               }
            }
         }
      }
   },
   "swagger":"2.0"
}

Manual Approach

The manual approach for generating an OpenAPI document involves writing the specification file by hand in YAML or JSON format. This approach is particularly useful when you want complete control over the API design before its implementation, or when documenting an already existing API without relying on automated tools.

To write the OpenAPI specification file, you can refer to the official documentation for version 2.0 of the OpenAPI Specification, where you'll find information on required fields and how to describe endpoints, parameters, responses, and more. This detailed guide will help you understand how to properly structure the YAML or JSON file to meet OpenAPI standards.

A good example of using this approach is when creating a REST service using the methods outlined in the official InterSystems IRIS documentation.
You can find an introduction to how to develop and configure a REST application in IRIS by following this page of the documentation, which describes step-by-step the methods needed to expose a RESTful application with IRIS.