Article
· Feb 7, 2023 9m read
Open Exchange

OpenAPI Suite - Part 2

#Contest #REST API #InterSystems Ideas Portal #InterSystems IRIS #Open Exchange

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 converter.swagger.io if the specification version is less than 3.0 and another HTTP request to validator.swagger.io 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:

^swaggervalidator("ValidatorURL")="http://<hostname>"
^swaggervalidator("Port")=<port>
^swaggerconverter("ConverterURL")="http://<hostname>"
^swaggerconverter("Port")=<port>

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

Firstly, we prepare a post-start script (named init_openapisuite.sh):

#!/bin/bash

openapi_suite() {
iris session $ISC_PACKAGE_INSTANCENAME -U IRISAPP <<- END
Set ^swaggerconverter("ConverterURL") = "${CONVERTER_URL:-converter.swagger.io}"
Set ^swaggerconverter("Port") = "${CONVERTER_PORT:-80}"
Set ^swaggervalidator("ValidatorURL") = "${VALIDATOR_URL:-validator.swagger.io}"
Set ^swaggervalidator("Port") = "${VALIDATOR_PORT:-80}"
Halt
END
}

openapi_suite

exit 0

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

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

version: '3.6'
services:
  iris:
    build: 
      context: .
      dockerfile: Dockerfile
    restart: always
    command: --check-caps false --ISCAgent false -a /home/irisowner/irisdev/init_openapisuite.sh
    environment:
      - CONVERTER_URL=http://swagger-converter
      - CONVERTER_PORT=8080
      - VALIDATOR_URL=http://swagger-validator-v2
      - VALIDATOR_PORT=8080
    ports: 
      - 1972
      - 52796:52773
      - 53773
    volumes:
      - ./:/home/irisowner/irisdev
  swagger-converter:
    image: swaggerapi/swagger-converter:latest
    restart: always
    # optional, openapi-suite don't need port exposed
    ports:
      - 8085:8080
  swagger-validator-v2:
    image: swaggerapi/swagger-validator-v2:latest
    restart: always
    # optional, openapi-suite don't need port exposed
    ports:
      - 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 = "https://openapisuite.demo.community.intersystems.com/openapisuite"
; Specification could be an URL, filepath or a stream.
Set specification = "https://petstore3.swagger.io/api/v3/openapi.json"
; 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!

Check the related application on InterSystems Open Exchange
Discussion (2)2
Log in or sign up to continue