Set OpenAPI Properties with GET /api/mgmnt/v1/:namespace/spec/:application/
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?
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.
.png)
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.
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!).
@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.
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.
The general pattern that I would recommend is:
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.
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?"