Apex 23.2.8 ORDS 24.1.1
I recently created a Swagger application in Apex to document our REST services to consumers on other teams in our company.
There are many cases where the generated Swagger doc does not contain data I would like to see.
An incomplete list of examples:
- Even though parameter table has a Comments field, the description in the Swagger doc is always “Implicit” or “Implicit parameter"
- No matter what mimetypes are allowed on the POST handler, the generated doc always only contains
- It would be nice to have a way to capture more complicated schemas for request bodies other than {body_text: “string”}.
- The ability to document enumerated values for fields.
For now, I am using the resource handler comments field to capture explanatory notes. I know I could create some custom tables and hand-edit the Swagger docs, but it would be more useful and less time-consuming for our services to be self-documenting. (Even a field on the service handler that allowed developers to create a custom document that got exported with the generated Swagger document would be preferable to what is there now.)
My question… Is there anything on the horizon to address the currently limited Swagger/openapi generated documents? The direction I go with this project depends on the answer.