· Feb 7, 2023 9m read

OpenAPI Suite - Part 2

Hi Community,

In the first part, we describe all packages, used libraries and REST services.

Now, I would like to add some details about converter and validator services.

By default, OpenAPI-Suite sends an HTTP request to if the specification version is less than 3.0 and another HTTP request to to simplify the structure of the specification document.  

Although the usage of online utilities is convenient, in some cases it could be better to have our own instance of the converter and validator.  For example, if OpenAPI-Suite is provided on a server in an organisation for ObjectScript developers, it may be preferable to avoid requests to external services (privacy, avoid request rate limits). 

Just run: 

docker run -d -p 8085:8080 --name swagger-converter swaggerapi/swagger-converter:latest
docker run -d -p 8086:8080 --name swagger-validator-v2 swaggerapi/swagger-validator-v2:latest

Open your browser at http://localhost:8085/ and http://localhost:8086/ and you have access to the UI of these services.  

OpenAPI-Suite need to be configured, to use local services, for that open an IRIS terminal and set the following globals:


Now let's see how to integrate this into our docker-compose and do it automatically.

Firstly, we prepare a post-start script (named


openapi_suite() {
Set ^swaggerconverter("ConverterURL") = "${}"
Set ^swaggerconverter("Port") = "${CONVERTER_PORT:-80}"
Set ^swaggervalidator("ValidatorURL") = "${}"
Set ^swaggervalidator("Port") = "${VALIDATOR_PORT:-80}"


exit 0

This script will be run by the iris-main program.  Check the script has "execute" rights (chmod +x  

And then we can create a docker-compose file like that:

version: '3.6'
      context: .
      dockerfile: Dockerfile
    restart: always
    command: --check-caps false --ISCAgent false -a /home/irisowner/irisdev/
      - CONVERTER_URL=http://swagger-converter
      - CONVERTER_PORT=8080
      - VALIDATOR_URL=http://swagger-validator-v2
      - VALIDATOR_PORT=8080
      - 1972
      - 52796:52773
      - 53773
      - ./:/home/irisowner/irisdev
    image: swaggerapi/swagger-converter:latest
    restart: always
    # optional, openapi-suite don't need port exposed
      - 8085:8080
    image: swaggerapi/swagger-validator-v2:latest
    restart: always
    # optional, openapi-suite don't need port exposed
      - 8086:8080

All resources are available on this repository, if you have already cloned it just do a "git pull" to get the latest updates.  Then, you can start OpenAPI-Suite with all the services locally with the following command: 

docker-compose --file docker-compose-with-swagger.yml up -d
; or for compose plugin users
; docker compose --file docker-compose-with-swagger.yml up -d


This is just an idea, but if the OpenAPI-Suite implementation becomes complete enough, perhaps It could be used to offer online ObjectScript code generation services from Swagger 3.0.  Currently, the application is hosted on dc demo server, this gave me the idea to make a tiny client for openapi-suite (it was also generated by openapi-suite itself! ).  So, it's possible to benefit from remote code generation without having to install all the tools locally:

zpm "install openapi-suite-client"


; remote openapi-suite REST service url : 
Set server = ""
; Specification could be an URL, filepath or a stream.
Set specification = ""
; Package name for generated classes.
Set packageName = "petstoreclient"
; available type : 
; - "client" : to generate http client classes. 
; - "production" :  to generate production client classes.
; - "rest" : to generate REST server classes
Set type = "client"
; Request and Install the generated code.
Set sc = ##class(dc.openapi.suite.client.RemoteCodeGen).Generate(specification, packageName, type, server)
Terminal output

Thank you!

Discussion (2)2
Log in or sign up to continue