Written by

Lorenzo Scalese

Solution Architect at Zorgi

Article Lorenzo Scalese · Feb 7, 2023 9m read

Open Exchange

OpenAPI Suite - Part 2

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

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 classesSet type = "client"; Request and Install the generated code.Set sc = ##class(dc.openapi.suite.client.RemoteCodeGen).Generate(specification, packageName, type, server)

Terminal output

IRISAPP>Set sc = ##class(dc.openapi.suite.client.RemoteCodeGen).Generate(specification, packageName, type, server)

Load started on 02/06/202320:49:19
Loading file /usr/irissys/mgr/Temp/Lgm86wQGGdNSiQ.xml as xml
Imported class: petstoreclient.HttpClient
Imported class: petstoreclient.model.Address
Imported class: petstoreclient.model.ApiResponse
Imported class: petstoreclient.model.Category
Imported class: petstoreclient.model.Customer
Imported class: petstoreclient.model.Order
Imported class: petstoreclient.model.Pet
Imported class: petstoreclient.model.Tag
Imported class: petstoreclient.model.User
Imported class: petstoreclient.model.spec
Imported class: petstoreclient.requests.addPet
Imported class: petstoreclient.requests.createUser
Imported class: petstoreclient.requests.createUsersWithListInput
Imported class: petstoreclient.requests.deleteOrder
Imported class: petstoreclient.requests.deletePet
Imported class: petstoreclient.requests.deleteUser
Imported class: petstoreclient.requests.findPetsByStatus
Imported class: petstoreclient.requests.findPetsByTags
Imported class: petstoreclient.requests.getInventory
Imported class: petstoreclient.requests.getOrderById
Imported class: petstoreclient.requests.getPetById
Imported class: petstoreclient.requests.getUserByName
Imported class: petstoreclient.requests.loginUser
Imported class: petstoreclient.requests.logoutUser
Imported class: petstoreclient.requests.placeOrder
Imported class: petstoreclient.requests.updatePet
Imported class: petstoreclient.requests.updatePetWithForm
Imported class: petstoreclient.requests.updateUser
Imported class: petstoreclient.requests.uploadFile
Imported class: petstoreclient.responses.GenericResponse
Imported class: petstoreclient.responses.addPet
Imported class: petstoreclient.responses.createUser
Imported class: petstoreclient.responses.createUsersWithListInput
Imported class: petstoreclient.responses.deleteOrder
Imported class: petstoreclient.responses.deletePet
Imported class: petstoreclient.responses.deleteUser
Imported class: petstoreclient.responses.findPetsByStatus
Imported class: petstoreclient.responses.findPetsByTags
Imported class: petstoreclient.responses.getInventory
Imported class: petstoreclient.responses.getOrderById
Imported class: petstoreclient.responses.getPetById
Imported class: petstoreclient.responses.getUserByName
Imported class: petstoreclient.responses.loginUser
Imported class: petstoreclient.responses.logoutUser
Imported class: petstoreclient.responses.placeOrder
Imported class: petstoreclient.responses.updatePet
Imported class: petstoreclient.responses.updatePetWithForm
Imported class: petstoreclient.responses.updateUser
Imported class: petstoreclient.responses.uploadFile
Compiling 49 classes
Compiling class petstoreclient.HttpClient
Compiling class petstoreclient.model.Address
Compiling class petstoreclient.model.Category
Compiling class petstoreclient.model.ApiResponse
Compiling class petstoreclient.model.Customer
Compiling class petstoreclient.model.Order
Compiling class petstoreclient.model.Tag
Compiling class petstoreclient.model.Pet
Compiling class petstoreclient.model.spec
Compiling class petstoreclient.requests.addPet
Compiling class petstoreclient.model.User
Compiling class petstoreclient.requests.createUser
Compiling class petstoreclient.requests.deleteOrder
Compiling class petstoreclient.requests.createUsersWithListInput
Compiling class petstoreclient.requests.deleteUser
Compiling class petstoreclient.requests.deletePet
Compiling class petstoreclient.requests.findPetsByStatus
Compiling class petstoreclient.requests.findPetsByTags
Compiling class petstoreclient.requests.getInventory
Compiling class petstoreclient.requests.getOrderById
Compiling class petstoreclient.requests.getPetById
Compiling class petstoreclient.requests.getUserByName
Compiling class petstoreclient.requests.loginUser
Compiling class petstoreclient.requests.logoutUser
Compiling class petstoreclient.requests.updatePet
Compiling class petstoreclient.requests.placeOrder
Compiling class petstoreclient.requests.updateUser
Compiling class petstoreclient.requests.updatePetWithForm
Compiling class petstoreclient.requests.uploadFile
Compiling class petstoreclient.responses.GenericResponse
Compiling class petstoreclient.responses.createUser
Compiling class petstoreclient.responses.addPet
Compiling class petstoreclient.responses.deleteOrder
Compiling class petstoreclient.responses.createUsersWithListInput
Compiling class petstoreclient.responses.deletePet
Compiling class petstoreclient.responses.deleteUser
Compiling class petstoreclient.responses.findPetsByTags
Compiling class petstoreclient.responses.findPetsByStatus
Compiling class petstoreclient.responses.getOrderById
Compiling class petstoreclient.responses.getInventory
Compiling class petstoreclient.responses.getPetById
Compiling class petstoreclient.responses.getUserByName
Compiling class petstoreclient.responses.logoutUser
Compiling class petstoreclient.responses.loginUser
Compiling class petstoreclient.responses.placeOrder
Compiling class petstoreclient.responses.updatePet
Compiling class petstoreclient.responses.updatePetWithForm
Compiling class petstoreclient.responses.updateUser
Compiling class petstoreclient.responses.uploadFile
Compiling routine petstoreclient.HttpClient.1
Compiling routine petstoreclient.model.Address.1
Compiling routine petstoreclient.model.ApiResponse.1
Compiling routine petstoreclient.model.Category.1
Compiling routine petstoreclient.model.Customer.1
Compiling routine petstoreclient.model.Order.1
Compiling routine petstoreclient.model.Tag.1
Compiling routine petstoreclient.model.Pet.1
Compiling routine petstoreclient.requests.addPet.1
Compiling routine petstoreclient.model.User.1
Compiling routine petstoreclient.requests.createUser.1
Compiling routine petstoreclient.requests.createUsersWithListInput.1
Compiling routine petstoreclient.requests.deleteOrder.1
Compiling routine petstoreclient.requests.deletePet.1
Compiling routine petstoreclient.requests.deleteUser.1
Compiling routine petstoreclient.requests.findPetsByStatus.1
Compiling routine petstoreclient.requests.getInventory.1
Compiling routine petstoreclient.requests.findPetsByTags.1
Compiling routine petstoreclient.requests.getOrderById.1
Compiling routine petstoreclient.requests.getPetById.1
Compiling routine petstoreclient.requests.getUserByName.1
Compiling routine petstoreclient.requests.loginUser.1
Compiling routine petstoreclient.requests.logoutUser.1
Compiling routine petstoreclient.requests.placeOrder.1
Compiling routine petstoreclient.requests.updatePet.1
Compiling routine petstoreclient.requests.updatePetWithForm.1
Compiling routine petstoreclient.requests.updateUser.1
Compiling routine petstoreclient.requests.uploadFile.1
Compiling routine petstoreclient.responses.GenericResponse.1
Compiling routine petstoreclient.responses.addPet.1
Compiling routine petstoreclient.responses.createUser.1
Compiling routine petstoreclient.responses.deleteOrder.1
Compiling routine petstoreclient.responses.createUsersWithListInput.1
Compiling routine petstoreclient.responses.deletePet.1
Compiling routine petstoreclient.responses.deleteUser.1
Compiling routine petstoreclient.responses.findPetsByTags.1
Compiling routine petstoreclient.responses.findPetsByStatus.1
Compiling routine petstoreclient.responses.getInventory.1
Compiling routine petstoreclient.responses.getOrderById.1
Compiling routine petstoreclient.responses.getPetById.1
Compiling routine petstoreclient.responses.loginUser.1
Compiling routine petstoreclient.responses.getUserByName.1
Compiling routine petstoreclient.responses.logoutUser.1
Compiling routine petstoreclient.responses.updatePet.1
Compiling routine petstoreclient.responses.placeOrder.1
Compiling routine petstoreclient.responses.updatePetWithForm.1
Compiling routine petstoreclient.responses.updateUser.1
Compiling routine petstoreclient.responses.uploadFile.1
Load finished successfully.

IRISAPP>

Thank you!

Discussion (2)0

Add reply

Comments

Stefan Cronje · Feb 10, 2023

Good concept, Good start.
Would you mind contributions on GitHub?

0 0

Lorenzo Scalese Feb 11, 2023 to Stefan Cronje

Thank you @Stefan Cronje !

All contributions are welcome.

I will create as soon as possible a list of issues for improvement.

People who wish to contribute are welcome.

0 0