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
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!
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
.disp class
Hello @Gabriel Santos
AFAIK, The required property keyword works on literal, Collection, stream, serial, object valued properties except the %DynamicArray and %DynamicObject. Because by default the property methods(Getter) was created and it assign the values for %DynamicArray is "[]" and "{}" for dynamicObject even though if you assign empty string it overwrites it. so, The %ValidateObject() doesn't include these two objects for validation.