OpenAPI Spec - Unused components and using $ref

[CarlLusty]

Hello,

I have been looking at the API Spec and I have a few questions.

In the json file there are eight components that are defined but do not appear to be used directly.

• Channel
• Site
• Range
• TariffInformation
• Interval
• Renewable
• UnauthorizedError
• InternalServerError

Using Site as an example, a quick diff shows that the component Site and the response to the call '/sites' is basically the same, obviously with the call returning an array of Sites.

Is there a reason this is not specified in the Operation Object using a ref? ie. "$ref": "#/components/schemas/Site"

Types used in many operations, such as Range, are duplicated a lot in the Spec document. Using ref would also assist generators in creating more sane API interface code. As it stands, something like Range is likely to be generated as a distinct class or struct for every Operation/call that it is used in. Using a single type definition and refs would allow generators to create one Range structure and reused it.

I'm sure there is a good reason, but I am curious.

Carl.

[madpilot]

It’s been so long since I wrote that, but I seem to remember the swagger to typescript generator we used internally at the time vomitting hard on refs, so I manually resolved them.

I can see if that is still the case.

[madpilot]

I've made the requested changes and added a copy of the swagger.json file to this repo, so you can test before I publish to the main repo. This will also allow PRs.

https://github.com/amberelectric/public-api/blob/main/swagger.json

[madpilot]

Refs seem fine now. Have updated. Please look and if the changes look fine, I'll push to the main repo on Monday.

[madpilot]

All PRs and changes merged and deployed. The new schema is available at https://app.amber.com.au/swagger.json