API documentation issues

[marcus-bcl]

What should change

After following the guide to generate API documentation from an OpenAPI spec, we've found that Array/List responses are rendered incorrectly - they appear as empty objects.

For example, see: https://ministryofjustice.github.io/hmpps-probation-integration-services/tech-docs/projects/create-and-vary-a-licence-and-delius/api-reference.html#probation-case-crn-addresses

The response should appear as a a list of objects as they do in Swagger, for example: https://create-and-vary-a-licence-and-delius-dev.hmpps.service.justice.gov.uk/swagger-ui/index.html#/probation-case-resource/findAddresses

[anahickmann]

I've had a similar problem with list of strings getting displayed as a list with one empty object.

This is how the response is getting displayed (i.e. an array with one empty object):

And this is how it should get displayed (i.e. an array with one string):

[ntsim]

On our API docs, we found the generated docs inadequate and essentially re-implemented the entire thing to suit our use-case.

There's fairly substantial parts of the OpenAPI spec that aren't covered by the gem's built-in implementation such as polymorphic types (which we've used extensively in our API).

For anyone interested, we created a new module which we load in through config.rb. We then have a bunch of helpers that we use throughout the various templates:

• Config
• Extension
• Helpers
• Schema template
• Endpoint template

This is by no means a complete implementation so your mileage may vary. It should still be a useful starting point for anyone wanting to improve their generated docs!