Generación de Especificaciones OpenAPI

Introducción

Una API REST (Representational State Transfer) es una interfaz que permite que diferentes aplicaciones se comuniquen entre sí a través del protocolo HTTP, utilizando operaciones estándar como GET, POST, PUT y DELETE. Las API REST son ampliamente utilizadas en el desarrollo de software para exponer servicios accesibles por otras aplicaciones, permitiendo la integración entre diferentes sistemas.

Sin embargo, para garantizar que las API sean fáciles de comprender y utilizar, es fundamental contar con una buena documentación. Aquí es donde entra en juego OpenAPI.

OpenAPI es un estándar para la descripción de API RESTful. Permite definir de manera estructurada el funcionamiento de una API, especificando los endpoints disponibles, los tipos de datos aceptados y devueltos, los parámetros requeridos y las respuestas esperadas. Toda esta información se recopila en un archivo de especificación (generalmente con extensión .yaml o .json), que puede ser interpretado por herramientas automáticas para generar código, documentación y más.

La especificación OpenAPI está diseñada para ser legible tanto por máquinas como por humanos, permitiendo describir, producir, consumir y visualizar servicios web RESTful de manera estandarizada. Por lo tanto, un documento OpenAPI representa una descripción formal de la API, útil tanto para los desarrolladores que necesitan utilizarla como para las herramientas que pueden aprovecharla para automatizar diversos procesos.

¿Por qué es útil definir un archivo de especificación?

Adoptar OpenAPI para documentar una API ofrece varios beneficios:

• Claridad: Proporciona una documentación detallada y estructurada, permitiendo a los desarrolladores comprender rápidamente cómo interactuar con la API, qué solicitudes enviar y qué datos esperar en la respuesta.
• Automatización: La documentación puede generarse automáticamente a partir del código, manteniéndose siempre actualizada con los cambios en la API.
• Interactividad: Existen herramientas como Swagger, un conjunto de soluciones de código abierto para la documentación y prueba de API REST, que incluyen Swagger UI. Esta permite explorar y probar las API directamente desde el navegador, simplificando el desarrollo, la verificación y la comprensión de las API.
• Estandarización: Al utilizar OpenAPI, la documentación sigue un formato compartido y reconocido, facilitando la integración con otras herramientas y servicios.

¿Cómo se puede generar un documento OpenAPI?

Existen dos enfoques principales para generar un archivo de especificación OpenAPI:

• Enfoque "Code-first" (automático): Si ya se ha desarrollado una API REST en InterSystems IRIS, se puede generar automáticamente la documentación OpenAPI sin necesidad de escribir manualmente el archivo de especificación. IRIS ofrece una funcionalidad integrada que permite exportar la documentación OpenAPI en formato JSON o YAML, basándose en las definiciones de las clases REST.
• Enfoque "Specification-first" (manual): En este caso, el archivo OpenAPI se escribe manualmente en YAML o JSON, describiendo todos los endpoints, parámetros y respuestas esperadas. Este enfoque es útil cuando se desea definir la API antes de implementarla, facilitando su diseño y la comunicación con otros desarrolladores o partes interesadas.

Enfoque Automático

Para generar automáticamente el archivo de especificación OpenAPI, puedes utilizar la función GetWebRESTApplication proporcionada por la clase %REST.API.
Un ejemplo práctico de cómo utilizarla es agregando la siguiente función en la clase de dispatch:

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
}

Además, agrega la siguiente ruta a la UrlMap:

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

En este punto, tendrás todo lo necesario para generar el archivo de especificación desde tu clase de dispatch. Para visualizar la documentación, conéctate a la URL indicada (donde MyWebapp es el nombre de tu aplicación web, tal como está definida en el portal de administración):

<host>:<port>/MyWebapp/openapi

El JSON generado puede visualizarse y probarse con herramientas como 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"
}

Enfoque Manual

El enfoque manual para generar un documento OpenAPI consiste en escribir el archivo de especificación manualmente en formato YAML o JSON. Este enfoque es especialmente útil cuando se desea tener un control total sobre el diseño de la API antes de su implementación, o cuando se documenta una API ya existente sin depender de herramientas automatizadas.

Para escribir el archivo de especificación OpenAPI, puedes consultar la documentación oficial de la versión 2.0 de la OpenAPI Specification, donde encontrarás información sobre los campos requeridos y cómo describir los endpoints, parámetros, respuestas y más. Esta guía detallada te ayudará a comprender cómo estructurar correctamente el archivo YAML o JSON para cumplir con los estándares de OpenAPI.

Un buen ejemplo de este enfoque es cuando se crea un servicio REST utilizando los métodos descritos en la documentación oficial de InterSystems IRIS. Puedes encontrar una introducción sobre cómo desarrollar y configurar una aplicación REST en IRIS en la siguiente página de la documentación, que describe paso a paso los métodos necesarios para exponer una aplicación RESTful con IRIS.