openapi-suite

This package gather a set of tools for ObjectScript code generation from Swagger specification 3.0.

It includes :

• openapi-server-gen OEX link
• openapi-client-gen OEX link
• openapi-common-lib OEX link

The following features are available :

• Web interface to generate the code.
• REST services to expose code generation.
• Automatic conversion of Swagger specification 1.x or 2.x to version 3.x before processing (using swagger-converter-cli ).

OpenAPI-suite can generate code :

• Simple HTTP client
• Production client (with business services, processes and operation)
• Server-side REST classes.

Installation ZPM

zpm "install openapi-suite"
; optional
zpm "install swagger-ui"

Installation docker

git clone git@github.com:lscalese/openapi-suite.git
cd openapi-suite
# in case of permission issue with iris-main.log
# touch iris-main.log && chmod 777 iris-main.log
docker-compose up -d

Important : If you use url to a specification accessible only from your network \ organization use the docker-compose that include
validator and converter tools instead of the default docker-compose.yml:

docker-compose --file docker-compose-with-swagger.yml up -d

Note:
It seems a problem could be occurs with BuildKit on Ubuntu.
In this case, you should use the compose plugin with the command docker compose up -d plugin instead of docker-compose up -d.
See the official documentation to instal compose plugin : Install the Compose plugin | Docker Documentation

Usage

Web interface

The UI is available at this address(*) http://localhost:52796/openapisuite/ui/index.csp

By default the feature Install On Server is disabled.
To enable, just :

Set ^openapisuite.config("web","enable-install-onserver") = 1

(*) Adapt the port number if needed

Swagger-ui

If you install swagger-ui, you can open http://localhost:52796/swagger-ui/index.html and explore
http://localhost:52796/openapisuite/_spec to test REST services.

Generate by programming

All code snipets are available in the class dc.openapi.suite.samples.PetStore

Simple HTTP client

Set sc = ##class(dc.openapi.suite.Generate).Client("petstore.client", "https://petstore3.swagger.io/api/v3/openapi.json")

Production client

Set sc = ##class(dc.openapi.suite.Generate).ProductionClient("petstore.production","https://petstore3.swagger.io/api/v3/openapi.json")

Rest server-side classes

Set sc = ##class(dc.openapi.suite.Generate).Server("petstore.server", "https://petstore3.swagger.io/api/v3/openapi.json")

Code generation with a specification contains external references

If the input of your specification is a URL, the parser will resolve automatically external references like:

{
    "didDocument":{
        "$ref":"../common/ssi_types.yaml#/components/schemas/DIDDocument"
    }
}

Howewer, the name of the model is auto generated and there is way to have a better result.
Start to generate models from the referenced specification, then map the “$ref” with the model package before generate your app, example:

; Generate models from referenced specification
Set sc = ##class(dc.openapi.suite.Generate).Models("Nuts.Api.Common", "https://nuts-node.readthedocs.io/en/stable/_static/common/ssi_types.yaml")
; Set a mapping specifcation - models

Set externals =  {"../common/ssi_types.yaml": "Nuts.Api.Common.model"}
; Generate your application with a mapping model for external references.

Set sc = ##class(dc.openapi.suite.Generate).Server("Nuts.ApiServer.DidManager", "https://nuts-node.readthedocs.io/en/stable/_static/didman/v1.yaml", , externals)

Note: If you use a filepath instead of a URL, the solution above is the only way.

The features argument

The code generation methods described above can take 3rd argument features, this is an array with the following supported key-value:

Set features("noExtRef") = 1    ; avoid resolving external references by the parser.
; The following key\value make sense for ProductionClient generator:

;

Set features("noBS") = 1        ; no business service class generation

Set features("noBP") = 1        ; no business process class generation

Set features("noUtils") = 1     ; no utils class generation
; Example:

;

Set sc = ##class(dc.openapi.suite.Generate).ProductionClient("petstore.production","https://petstore3.swagger.io/api/v3/openapi.json", .features)

Developer community article

More information about OpenAPI-suite are available on this developer community article.

Troubleshoot

Due to many changes, recently you could experienced issue with your environment (zpm install error, problem to generate from an URL).
Before creating an issue please try this procedure to have a clean install and try again:

zpm "uninstall objectscript-openapi-definition"
zpm "uninstall openapi-common-lib"
zpm "uninstall openapi-client-gen"
zpm "uninstall openapi-server-gen"
zpm "uninstall swagger-validator-cli"
zpm "uninstall swagger-converter-cli"
zpm "uninstall openapi-suite"
zpm "install openapi-suite"