Set OpenAPI Properties with GET /api/mgmnt/v1/:namespace/spec/:application/

Question

Question

#API #CSP #REST API #InterSystems IRIS #InterSystems IRIS for Health

When manually coding REST services and using GET /api/mgmnt/v1/:namespace/spec/:application/ to return an OpenAPI spec, how do you specify supported properties (OpenAPI Properties in Use | Creating REST Services | InterSystems IRIS Data Platform 2021.1) like responses, definitions, and information in paths like summary and description?

GET /api/mgmnt/v1/:namespace/spec/:application/ | Creating REST Services | InterSystems IRIS Data Platform 2022.2

Using a very basic manual REST service that returns a JSON string I get a pretty basic spec that is not really helpful when it comes to documentation. I think the code-first approach would be useful for our purposes if we could make the resulting spec a bit more robust.

For context, I'm exploring the pros and cons of manual creation and spec first creation. Manual is simpler in terms of only needing a dispatch class to implement, but documentation becomes more cumbersome. Spec first creation is great on the documentation side, but when you are coding client-side it makes development process a bit more cumbersome. I have also looked at isc.rest.

Product version: IRIS 2022.1

$ZV: IRIS for Windows (x86-64) 2022.1.2 (Build 574U) Fri Jan 13 2023 15:00:26 EST

Discussion (7)3

Log in or sign up to continue

Timothy Leavitt · Feb 27

The general pattern that I would recommend is:

Use isc.rest (https://github.com/intersystems/isc-rest) to create APIs to existing (or new) data and business logic
Use isc.ipm.js (https://github.com/intersystems/isc-ipm-js) to generate client code - once it's set up, getting an updated OpenAPI spec file and - on top of that - updated Angular services and TypeScript model classes (for example) is as easy as running zpm "package-name generate"

https://github.com/intersystems/isc-perf-ui is a simple example of how this all fits together - see especially https://github.com/intersystems/isc-perf-ui/blob/main/module.xml.

I just used this toolset to build a small but meaningful IRIS-based application in about a week. I didn't hand-code a single REST endpoint in ObjectScript, and I got my OpenAPI spec and all my Angular services and TypeScript interfaces for free*.

Of course, if you already have a significant hand-coded REST API, this doesn't help much. For one application my team manages we've added a Forward in our main REST dispatch class to one using isc.rest and gradually migrated endpoints over to use the standardized approach.

* ok, not totally free - there's the small price of writing better ObjectScript and e.g. having methods that return a registered JSON-enabled type rather than e.g. %DynamicArray and %DynamicObject.

0 0

score 0 · Answer 1 · 2023-02-16T09:24:46-05:00

I have the exact same question! Can someone please provide a response to this? For what we are trying to implement, spec-first is not really sustainable, but I do want to be able to have the Swagger API documentation being updated on-the-fly via this process. But as the OC pointed out, these attributes are missing in the code-first approach and we'd like to know how to add them, if at all possible (and I really hope it is!).

score 0 · Answer 2 · 2023-02-21T13:25:10-05:00

@Jason Jones after I posted this I forgot that @Timothy Leavitt had sent me this example of Open API generation not as an alternative to api/mgmt/v1 but as an alternative to using the package manager and the isc-rest opensource code.

isc-ipm-js/openApiProcessor.cls at main · intersystems/isc-ipm-js (github.com)

I'm not exactly sure this answers my question about using api/mgmt/v1 to generate the spec but it could lead to some clues? You can see the discussion here:

Projecting JSON · Discussion #22 · intersystems/isc-rest (github.com)

There's a lot to examine here but I don't think it's the simple solution we're looking for. I personally have been sticking with the IS spec first approach as it's quite easy to implement so far. The biggest challenge has been developing on the client side when the source code is generated on the server.

score 0 · Answer 3 · 2023-02-27T08:30:06-05:00

Thanks for the reply, but I'm not seeing that this answers your original, and my duplicate, question about how to provide certain OpenAPI attributes when coding IRIS REST services using the manual approach. I wish I could use the spec-first approach but I don't see how that would work in my organization. We have a need to do things in such a way that the manual approach is going to be the only feasible way to make it work, without getting too down in the weeds with an explanation. So I'm just looking for a way to modify my exiting REST classes, that extend %CSP.REST, or perhaps add a class to my service class suite (that includes the Dispatch class, so that it provides the necessary OpenAPI spec attributes.

score 0 · Answer 4 · 2023-02-28T13:53:00-05:00

Yes, we have a significant REST hand-coded API already in place and in use. I was hoping there were attributes I could add to my existing classes that would "fill in" the missing OpenAPI attributes when calling GET /api/mgmnt/v1/:namespace/spec/:application/ to pull the OpenAPI spec for a Swagger UI. So, bottom line is, there is no solution? Or the solution is "don't hand-code services, use isc-rest?"

score 0 · Answer 5 · 2023-07-19T16:29:46-04:00

I gave up on this and we manually create rest services and documentation. It's tedious but I don't think this was going to do what I wanted to do and we aren't keen on using Open-Exchange stuff that's not directly supported by IS.

score 0 · Answer 6 · 2023-07-20T10:06:40-04:00

I finally gave up as well and converted our development over to the OpenApi-YAML-first method of development, and it works well now for us. I like the fact that we have a dynamically-maintained "live" spec file that we can tap into from a Swagger UI that lets developers see and test our API. Now that I'm on the other side, I can see this is a much better method than the way I was doing it. That's not to say it will work for everyone but I'd recommend everyone at least give it a try - it might work better than you think. At least it did for me.