Representing the standards in OAS 3

[JamesMBligh]

Created the issue to continue the discussion from: https://github.com/ConsumerDataStandardsAustralia/standards/issues/149#issuecomment-770499875

In the comment @perlboy posted:

@CDR-API-Stream If this is the case then the initial feedback would be to evaluate Redocs properly. create-openapi-repo exists to split an existing spec into more manageable chunks and includes a structure to allow for efficient display of code examples as well as a way of injecting non-openapi markdown during rendering

An example of such a deployment is available at dsb-standards and includes an example of a travis ci build and npm deploy to github.

Fundamentally such an approach would significantly aid implementers to understand the changes made per release far beyond the convoluted release process currently in place while resulting in a DRY approach to the DSB capable of effectively tracking impact of changes across multiple industries.

[JamesMBligh]

Thanks for the suggestions Stuart. I've been looking at decomposition of the spec and am aware of create-open-repo and your dsb-standards repo. Migrating to v3x of OAS gives us a lot more opportunity with inclusion using external $ref.

Publishing the energy standards using ReDoc was a step towards this. We wanted to understand if the change in format would be a problem for anyone (so far it doesn't seem to be).

Concerning decomposition, I don't think we will end up using the create-open-repo tooling verbatim as we need to find a way to handle end point versioning (potentially at the method level also). In particular we need to be able to accomodate multiple concurrent versions of the same end point (e.g. Get Product Detail v2 and v3 are both currently active).

The goal would be to create a repo with decomposed files so that the staging process we have defined will allow people to clearly see exactly what has been modified (both OAS and markdown) and the mechanism by which those files are then turned into static content is far less important and we can fade that into the background.

What has your experience been maintaining the dsb-standards site as changes have been incorporated into the standards, especially with versioning? I noticed that only v3 of Get Products is included for instance.

[perlboy]

Thanks for the suggestions Stuart. I've been looking at decomposition of the spec and am aware of create-open-repo and your dsb-standards repo. Migrating to v3x of OAS gives us a lot more opportunity with inclusion using external $ref.

Swagger supported $ref and external referencing in redocs is only partially supported.

Publishing the energy standards using ReDoc was a step towards this. We wanted to understand if the change in format would be a problem for anyone (so far it doesn't seem to be).

But this isn't publishing using ReDoc, this is rendering using ReDoc. Essentially the only thing being tested is whether people like the colour scheme.

Concerning decomposition, I don't think we will end up using the create-open-repo tooling verbatim as we need to find a way to handle end point versioning (potentially at the method level also). In particular we need to be able to accomodate multiple concurrent versions of the same end point (e.g. Get Product Detail v2 and v3 are both currently active).

That is what oneOf is for.

Addendum: The application of version number suffix for individual models was first requested on 11 December 2019: https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/61

The goal would be to create a repo with decomposed files so that the staging process we have defined will allow people to clearly see exactly what has been modified (both OAS and markdown) and the mechanism by which those files are then turned into static content is far less important and we can fade that into the background. What has your experience been maintaining the dsb-standards site as changes have been incorporated into the standards, especially with versioning? I noticed that only v3 of Get Products is included for instance.

This is incorrect:

Please do more research on the ins and outs of Redoc.