Generate Swagger spec from persistent and serial classes

Eduard Lebedyuk · Jun 19, 2020

#API #Best Practices #Code Snippet #REST API #InterSystems IRIS

Recently I needed to generate a Swagger spec from persistent and serial classes, so I'm publishing my code (it's not complete - you still need to hash out the application specifics, but it's a start). It's available here.

Let's say you have these classes:

Classes

Class REST.Test.Person Extends %Persistent
{

/// Person's name.
Property Name As %String [ Required ];

/// Person's Social Security number. This is validated using pattern match.
Property SSN As %String [ Required ];

/// Person's Date of Birth.
Property DOB As %Date;

/// Person's home address. This uses an embedded object.
Property Home As Address;

/// Person's office address. This uses an embedded object.
Property Office As Address;

/// Person's spouse. This is a reference to another persistent object.
Property Spouse As Person;

/// A collection of strings representing the person's favorite colors.
Property FavoriteColors As list Of %String;

/// A collection of strings representing the person's favorite colors.
Property FavoriteNumbers As array Of %Integer;

/// Person's age.<br>
/// This is a calculated field whose value is derived from <property>DOB</property>.
Property Age As %Integer;

}

Class REST.Test.Address Extends %SerialObject
{

/// The street address.
Property Street As %String(MAXLEN = 80);

/// The city name.
Property City As %String(MAXLEN = 80);

/// The 2-letter state abbreviation.
Property State As %String(MAXLEN = 2);

/// The 5-digit U.S. Zone Improvement Plan (ZIP) code.
Property Zip As %String(MAXLEN = 5);
}

You can automatically generate this Swagger definition from them:

 REST.Test.Person:
   type: "object"
   properties:
     Age:
       type: "integer"
     DOB:
       type: "string"
     FavoriteColors:
       type: "array"
       items:
         type: "string"
     FavoriteNumbers:
       type: "object"
     Home:
       $ref: "#/definitions/REST.Test.Address"
     Name:
       type: "string"
     Office:
       $ref: "#/definitions/REST.Test.Address"
     SSN:
       type: "string"
     Spouse:
       $ref: "#/definitions/REST.Test.Person"
 REST.Test.Address:
   type: "object"
   properties:
     City:
       type: "string"
     State:
       type: "string"
     Street:
       type: "string"
     Zip:
       type: "string"

Main method: Utils.YAML:GenerateClasses

Test run: do ##class(Utils.YAML).Test()

XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ] { <Routes> <Route Url="/pets/:id" Method="delete" Call="deletePet" /> </Routes> } ClassMethod deletePet(pid As %String) As %Status { Try { If '##class(%REST.Impl).%CheckAccepts("application/json") Do ##class(%REST.Impl).%ReportRESTError(..#HTTP406NOTACCEPTABLE,$$$ERROR($$$RESTBadAccepts)) Quit If ($number(pid,"I")="") Do ##class(%REST.Impl).%ReportRESTError(..#HTTP400BADREQUEST,$$$ERROR($$$RESTInvalid,"id",id)) Quit Set response=##class(petstore.impl).deletePet(pid) Do ##class(petstore.impl).%WriteResponse(response) } Catch (ex) { Do ##class(%REST.Impl).%ReportRESTError(..#HTTP500INTERNALSERVERERROR,ex.AsStatus()) } Quit $$$OK }

Reply by José Roberto Pereira Aug 31, 2020

Hi Eduard.

Awesome job, congratulations!

Is there something similar but for REST Dispatcher classes?

00 0

Reply by Eduard Lebedyuk Aug 31, 2020

Can you elaborate a bit?

What dispatcher class do you want generated?

Sure! Let's say I have this dispatcher class:

Is there a way to generate a YAML documentation for the endpoint /pets/:id, HTTP DELETE method, like you did for REST.Test.Person class?

Sure:

Set sc=##class(%REST.API).GetWebRESTApplication(namespace,webApplication,.swagger)

10 0

Hmm... interesting... I think I didn't know that class beacuse I still didn't move to IRIS...

Thank you Eduard.

Reply by Timothy Leavitt Aug 31, 2020

FYI, we're looking to add automatic OpenAPI generation to https://github.com/intersystems/apps-rest at some point in the reasonably-near future. (We had an intern work on it over the summer, and are just kicking the tires on it a bit on our own REST models/APIs before unleashing it on the world.)

40 0

Thank you Timothy for let me know.

Reply by Guillaume Rongier Sep 1, 2020

Don't know if that can help, but with this module, you can do the other way around from swagger generate persitent classes.

https://openexchange.intersystems.com/package/objectscript-openapi-defin...

Reply by José Roberto Pereira Sep 1, 2020

Hi Guillaume.

One more cool feature to explore when my company moves to IRIS. :)

Thank you for let me know.

Reply by Developer Commu... Sep 4, 2020

💡 This article is considered as InterSystems Data Platform Best Practice.

Primary tabs

Generate Swagger spec from persistent and serial classes

Replies