_spec para swagger-ui desde la clase de spec

Seguramente queríais usar la especificación OpenAPI (OAS) en formato JSON que utilizasteis para vuestra clase spec en el paquete iris-web-swagger-ui de IRIS.
La OAS generada por el método ##class(%REST.API).GetWebRESTApplication(...) es muy básica, sin descripciones de los parámetros ni de la estructura esperada de las respuestas.

Así que, después de crear vuestra aplicación REST a partir de una OAS, deberíais tener:

• Una clase application.disp.cls generada
• Una clase application.spec.cls (añadiremos una ruta hacia la especificación OpenAPI que se encuentra en la propiedad "XData OpenAPI")
• Una clase application.impl.cls (solo implementaremos el método GetSpec)

Si instalasteis el paquete iris-web-swagger-ui (https://openexchange.intersystems.com/package/iris-web-swagger-ui), necesitáis un endpoint que devuelva la OAS.

Mi enfoque consiste en añadir una ruta hacia la OAS en la clase spec y aplicarla usando la propiedad "OpenAPI" de dicha clase spec. Esto os permitirá, por ejemplo, tener disponible para pruebas toda la estructura del OAS original.

En la clase de ejemplo del paquete iris-web-swagger-ui (Sample.PersonREST), hay una implementación del método SwaggerSpec que actualiza algunas propiedades para reflejar lo que está configurado en la Aplicación Web de IRIS. Si seguís este procedimiento, recomiendo actualizar directamente la OAS en la clase spec para proporcionar esa información y así centralizar la documentación de vuestra API (aunque siempre podéis actualizarla en el método GetSpec que os muestro como ejemplo).

Siguiendo el ejemplo de la clase Sample.PersonREST, la ruta será /_spec. Aunque existe un valor para la etiqueta "basePath", este será reemplazado por el nombre de la Aplicación Web de IRIS.

Class application.spec Extends %REST.Spec [ProcedureBlock]
{

XData OpenAPI [ MimeType = application/json ]
{
{
  ...
  "basePath":"/api/myapi",
  ...
  "paths":{
    "/_spec": {
      "get":{
        "operationId":"GetSpec",
        "description":"This OpenAPI Spec",
        "produces":[
          "application/json"
        ],
        "responses":{
          "200":{
            "description":"Successful operation"
            }
          }
        }
    }, 
...

Lo siguiente es pegar este código sencillo en la clase de implementación. Concretamente, después de compilar la clase spec, la clase impl tiene un nuevo método (GetSpec) que debe devolver un objeto dinámico (el comentario principal proviene de la OAS en la clase spec y de la etiqueta "description" del "get" en la ruta). Debéis reemplazar "application.spec" por la referencia a vuestra propia clase de aplicación.

/// This OpenAPI Spec
ClassMethod GetSpec() As %DynamicObject
{
    Set spec = {}.%FromJSON(##class(%Dictionary.CompiledXData).%OpenId("application.spec||OpenAPI").Data.Read())
    Set spec.basePath = %request.Application
    Return spec
}

¡Eso es todo!

Ahora id a vuestro iris-web-swagger-ui (en mi caso, http://localhost:52773/swagger-ui/index.html) y probad explorando en “http://localhost:52773/api/myapi/_spec” dentro del campo de navegación de swagger-ui.

Nota: definí una Aplicación Web llamada /api/myapi con “application.disp” como su “clase de despacho” (Dispatch class).