ObjectScript OpenApi Definition Class Generator

Announcement

Guillaume Rongier · Apr 6, 2020

Open Exchange

#REST API #Open Exchange

InterSystems offers an API-design first approach.

You can check this post for more informations : https://community.intersystems.com/post/iris-api-explorer-application.

One practical thing about this approch and the OpenAPI specification is the definition of exchange objects.

The do ^%REST command does not create object definitions, but only routes and associated methods.

Output for the do ^%REST command for PetShop example :

USER>do ^%REST

REST Command Line Interface (CLI) helps you CREATE or DELETE a REST application.
Enter an application name or (L)ist all REST applications (L): PetShop
REST application not found: PetShop
Do you want to create a new REST application? Y or N (Y): Y
File path or absolute URL of a swagger document.
If no document specified, then create an empty application.
OpenAPI 2.0 swagger: https://petstore.swagger.io/v2/swagger.json

OpenAPI 2.0 swagger document: https://petstore.swagger.io/v2/swagger.json
Confirm operation, Y or N (Y):

-----Creating REST application: PetShop-----
CREATE PetShop.spec
GENERATE PetShop.disp
CREATE PetShop.impl
REST application successfully created.

Create a web application for the REST application? Y or N (Y):
Specify a web application name beginning with a single '/'. Default is /csp/PetShop
Web application name: /csp/petshop

-----Deploying REST application: PetShop-----
Application PetShop deployed to /csp/petshop

As we can see in this example, three classes were generated.

a disp class (not accessible to the user)
an impl class (which contains all API implementations)
a spec class (which contains the OpenApi definition in a block XData)

What if, we could create a package that would contain all the class definitions in the specification?

This is what we are going to do with this OpenExchange application available with ZPM.

To install it with zpm :

USER>zpm
zpm: USER>install objectscript-openapi-definition

[objectscript-openapi-definition]       Reload START
[objectscript-openapi-definition]       Reload SUCCESS
[objectscript-openapi-definition]       Module object refreshed.
[objectscript-openapi-definition]       Validate START
[objectscript-openapi-definition]       Validate SUCCESS
[objectscript-openapi-definition]       Compile START
[objectscript-openapi-definition]       Compile SUCCESS
[objectscript-openapi-definition]       Activate START
[objectscript-openapi-definition]       Configure START
[objectscript-openapi-definition]       Configure SUCCESS
[objectscript-openapi-definition]       Activate SUCCESS

Then you can use the library like this :

zw ##class(Grongier.OpenApi.Definition).Process("PetShop.spec")

Compilation started on 04/06/2020 15:40:49 with qualifiers ''
Compiling 6 classes, using up to 8 worker jobs
Compiling class PetShop.Definition.ApiResponse
Compiling class PetShop.Definition.Category
Compiling class PetShop.Definition.Tag
Compiling class PetShop.Definition.Order
Compiling class PetShop.Definition.Pet
Compiling class PetShop.Definition.User
Compiling routine PetShop.Definition.Tag.1
Compiling routine PetShop.Definition.Category.1
Compiling routine PetShop.Definition.Order.1
Compiling routine PetShop.Definition.ApiResponse.1
Compiling routine PetShop.Definition.User.1
Compiling routine PetShop.Definition.Pet.1
Compilation finished successfully in 0.183s.

And as you can see, the classes associated with the definitions have been generated.

These generated classes take into account :

mandatory fields
types
min/max values

For example you can cast a body into a definition as this :

ClassMethod addPet(body As %Stream.Object) As %Stream.Object

{

//Verify payload confirmity against definition

Set tPaylaod = ##class(PetShop.Definition.Pet).%New()

Set tSC = tPaylaod.%JSONImport(body)

If ($$$ISERR(tSC)) {

Do ..%ReportRESTError(500,tSC,1) Quit ""

}

Quit ""

}

You can find code and examples on this git repo : https://github.com/grongierisc/objectscript-openapi-definition

If you have any comments or questions, I will be happy to answer them.