New post
Question
· Jan 23

%REST.API swagger specs generation from comments / response type

#API #CSP #JSON #Namespace #REST API #InterSystems IRIS

Hi, I am currently setting up a new API using %CSP.REST - I've gotten swagger spec generation to work like such:

Class Api.DispatchRouter Extends %CSP.REST
{

XData UrlMap
{
<Routes>

<Map Prefix="/test" Forward="Api.Controllers.TestController"/>

<Route Url="/swagger" Method="GET" Call="SwaggerSpec"/>   
</Routes>
}

ClassMethod SwaggerSpec() As %Status
{
    Set tSC = ##class(%REST.API).GetWebRESTApplication($NAMESPACE, %request.Application, .swagger)
    Do swagger.info.%Remove("x-ISC_Namespace")
    Set swagger.basePath = "/csp/myapi"
    Set swagger.info.title = "My API"
    Set swagger.info.version = "0.0.0"
    Set swagger.host = "myhost.com"
    Return ..%WriteJSON($$$OK, swagger)
}

}

Class Api.Controllers.TestController Extends %CSP.REST
{

XData UrlMap
{
<Routes>

<Route Url="/:name" Method="GET" Call="Test"/>

</Routes>
}

/// This gets read by Swagger, can I add metadata here?
ClassMethod Test(name As %String) As %Status
{
    write "works!: " _ name, !
    Return $$$OK
}

}

 

This correctly reads all the endpoints inside the TestController based on the UrlMap, but it does not know the return type

I would like to be able to add additional info to each individual endpoint, for starters to manually define the possible return types/objects, as well as parameters from the %request, directly inside a comment above the ClassMethod.

 

I'd rather have it auto-generate the swaggerspec, so I'm wondering if anyone can point me in the right direction.

I have also heard of isc-rest package, but unless the features are outstanding, I'd prefer to stay away.

Product version: IRIS 2024.2
Discussion (3)1
Log in or sign up to continue
Ashok Kumar · Jan 23

Hello @Martin Nielsen

If you're mentioned the Return types( %Status or %Stream.Object) those are is IRIS specific and swagger 2.0 doesn't have those types . It has "response" object in swagger information/you have to define the response. ex: {"responses":{"200":{"description":"Successfully retrieved user","schema":{"$ref":"#/definitions/User"}},"404":{"description":"User not found"}}} 

Path Parameters are documented by default 
ex : "/mytest/{userid}"

"summary"  and "description"- you can use this OpenAPI properties to add description and additional information about the classmethod.

Please refer the below Swagger 2.0 sample.

note: If you're using spec-first approach. You need to do all the changes in .Impl class not in .disp class. Because .disp is generated class and it will be overwritten once .spec class compiled(updating swagger).

Swagger

 
Spoiler

.disp class

 
Spoiler
1 0
Martin Nielsen · Jan 24

Hi @Ashok Kumar 
perhaps I didn't make myself clear with my intention;

I want to be able to directly set metadata such as summary, responses, request parameters, etc. directly in the comment above each endpoint method (where I said "can I add metadata here?")

I don't mind if I have to make my own custom implementation to read these values, but I have no idea where to start right now, or whether I even should, perhaps there are already a solution available somewhere?

reason: The swagger spec generated is almost useless, because it does not specify the required parameters / payload for each respective endpoint, it only captures what is inside the UrlMap it seems.

Ideally I'd want to have my implementation of swagger to read the required request parameters / payload, but manually keeping docs updated through comments is a fine starter for my project, is any of this possible already or would I need to create a custom solution using %REST.API ?

EDIT: I just realized you're talking about using specification-first approach, I am talking about the opposite, implementation first, I'll look into going about the specification-first approach.

Thank you again for your help.

0 0
Ashok Kumar · Jan 24

As you know the swagger is used to design the API documentation first, and then build the REST API based on that design. IRIS or other API systems don't inherently know about the payload, the return response, or the specific responses for status codes like 200, 400, or 500 unless it's specified.

You're right about the traditional approach. Creating REST services manually doesn't have knowledge of these details. It generates the Swagger documentation based on the information available in the UrlMap and the class method in the dispatch class. Add your comments on top of the class method (meta data details) will be set into the description in swagger

 
Spoiler

If you want your API to be well-documented, it’s better to follow a spec-first approach, as this approach captures crucial details like paths, method types, descriptions, path parameters, query parameters, and responses.

Thanks!

1 0