3
1929

Written by

Eduard Lebedyuk
Senior Cloud Architect at InterSystems
STAFF
Follow
Article Eduard Lebedyuk · Jun 19, 2020 2m read

Generate Swagger spec from persistent and serial classes

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

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

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()

Discussion (14)6
Log in or sign up to continue

Comments

José Pereira · Aug 31, 2020

Hi Eduard.

Awesome job, congratulations!

Is there something similar but for REST Dispatcher classes?

0
Eduard Lebedyuk  Aug 31, 2020 to José Pereira

Can you elaborate a bit?

What dispatcher class do you want generated?

0
José Pereira  Aug 31, 2020 to Eduard Lebedyuk

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

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
}

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?

0
Eduard Lebedyuk  Aug 31, 2020 to José Pereira

Sure:

Set sc=##class(%REST.API).GetWebRESTApplication(namespace,webApplication,.swagger)
0
José Pereira  Aug 31, 2020 to Eduard Lebedyuk

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

Thank you Eduard.

0
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.)

0
José Pereira  Aug 31, 2020 to Timothy Leavitt

Thank you Timothy for let me know.

0
José Pereira  Sep 1, 2020 to Guillaume Rongier

Hi Guillaume.

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

Thank you for let me know.

0
Dan Goldman · Apr 15, 2022

I am looking to try and generate a swagger spec from a persistent class.  The link to the above mentioned code is not working. Could you repost the link or add the code to generate the spec?

Thanks Dan

0
Dan Goldman  Apr 15, 2022 to Guillaume Rongier

Thanks for the help!

0