OpenAPI documentation for REST-based services

OpenAPI JSON output

The following is sample JSON output:

{
  "openapi": "3.1.1",
  "info": {
    "title": "OpenAPI documentation for REST-based services",
    "description": "Provides APIs for REST-based services",
    "version": "1.1.0"
  },
  "servers": [
    {
      "url": "http://localhost:8820/demo/rest",
      "description": "Direct server configuration"
    },
    {
      "url": "{scheme}://{host}:{port}{ctx}/rest",
      "description": "Default server configuration",
      "variables": {
        "scheme": { "enum": ["http", "https"], "default": "http" },
        "host": { "default": "localhost" },
        "port": { "default": "8820" },
        "ctx": {
          "description": "The webapp/context for this service. Empty/blank indicates ROOT",
          "default": "/demo"
        }
      }
    },
    {
      "url": "{ctx}/rest",
      "description": "Default relative-path configuration",
      "variables": {
        "ctx": {
          "description": "The webapp/context for this service. Empty/blank indicates ROOT",
          "default": "/demo"
        }
      }
    }
  ],
  "paths": {
    "/mapped/hello": {
      "get": {
        "tags": ["mapped"],
        "summary": "HelloProc_sayHello",
        "description": "Invokes internal procedure in called ABL procedure",
        "operationId": "mapped_HP_sayHello",
        "parameters": [
          {
            "in": "query",
            "name": "toWhom",
            "required": false,
            "schema": { "type": "string", "description": "Query parameter" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": "{\"response\":{\"greeting\":\"string\"}}"
                }
              }
            }
          }
        }
      }
    }
  }
}

The output contains the OpenAPI format along with other standard properties defined by the OpenAPI standard. This includes supporting information such as the HTTP verb expected to access those services, schema information (when applicable), and a list of input and output parameters defined for each service. For parameters, only the expected external (HTTP) datatype is described, as the OpenAPI is a generic descriptor format and is server-language agnostic.

The servers array provides multiple URL options for accessing the REST services:

• A fully resolved URL pointing directly to the REST transport, for use by programmatic consumers that require an explicit base URL without variable substitution. The hostname in this URL is derived from the incoming request. If the client accesses the OpenAPI output using localhost, the URL reflects localhost. If the client uses an IP address (such as 127.0.0.1) or a fully-qualified domain name, that value is reflected instead.
• A relative-path entry using the webapp context variable.
• A parameterized entry with scheme, host, port, and context variables for flexible client configuration.

Each operation and its parameters include a description field with summary text describing the purpose and expected usage.

View output graphically in Swagger UI

Swagger UI can parse the JSON output in OpenAPI format, allowing you to view and interact with your REST services. A pre-packaged Swagger UI viewer is included with Progress Application Server (PAS) for OpenEdge and does not require external downloads or Content Delivery Network (CDN) access. To access it, follow these steps:

1. Deploy swaggerui.war to your PAS for OpenEdge instance by running the following command from a PROENV session:

   tcman deploy DLC/servers/pasoe/extras/swaggerui.war

2. Restart the PAS for OpenEdge instance after deployment:

   tcman oeserver -restart

3. Once deployed, access the viewer at:

   http://host:port/swaggerui/

By default, the viewer reads the OpenAPI output from the ROOT web application at ../server/rest/services/openapi. To view a different web application, enter its relative path in the URL field at the top of the page (for example, ../mywebapp/server/rest/services/openapi) and click Explore.

The following figure shows what the OpenAPI documentation looks like in Swagger UI for REST-based services: