Home Applications OpenAPI-Suite

OpenAPI-Suite

This application is not supported by InterSystems Corporation. Please be notified that you use it at your own risk.
5
4 reviews
1
Awards
974
Views
135
IPM installs
4
7
Details
Releases
Reviews
Awards
Issues
Pull requests
Articles
Dependencies
This app has a demo View
Set of tools for ObjectScript code generation from Swagger 3.0

What's new in this version

A lot of improvements and fixes.
Thank you Theo !

Improvements:

  • Add support for OpenAPI additionalProperties #32
  • Make sure responses other than 20x are also handled! #24
  • Allow generating GenericReponse as common message #22
  • Add support for "application/x-www-form-urlencoded"; generate new utility class util.UrlEncodedRequest #18
  • Allow suppressing of required qualifier, instead add “required” as part of description! #17

bugfixes:

  • Do not call SetParam for empty query variable #38
  • Move set path parameter in dispatch class #36
  • Make sure the description from responses is also generated as a comment #23
  • Request classes - Add MAXLEN="" for path properties and %URL #20

Gitter
Quality Gate Status
Reliability Rating

License: MIT

openapi-suite

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

It includes :

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"

Made with
Install
zpm install openapi-suite download archive
Version
1.1.024 Oct, 2023
Ideas portal
https://ideas.intersystems.com/ideas/DPI-I-226
ObjectScript quality test
Category
Solutions
Works with
InterSystems IRIS
First published
29 Jan, 2023
Last checked by moderator
27 Jun, 2023Works