There is a release of the Conjur OpenAPI spec

[izgeri]

We should consider when defining the spec release process whether we want to archive a versioned record of the spec and its human-readable markdown with the release - if we decide to do that, we should implement it in this card.

AC:

• [ ] The release process for the spec is defined in the CONTRIBUTING guide
• [ ] (optional) The automation for archiving releases is implemented
• [ ] A tag is added to the OpenAPI spec repo with version 5.1.0

Spec releases should include:

• A zip of the OSS spec
• ~A zip of the Enterprise spec~ TBA later
• A zip (?) of the Postman collection
• ~The specific Conjur API version they work with (what would be the relevant enterprise component that we should be matching the version to @micahlee ?)~

[telday]

Based on a conversation @john-odonnell & myself had about usability of the bundled spec artifact I think it will make the most sense to offer archived versions of both the individual spec files as well as a bundled spec file for use with third party tools which may not support cross file referencing.

However we should be sure to note in the download that it is not recommended to use the bundled version because you do lose some information (a generated client built on a bundled spec ends up having default model names).

[micahlee]

what would be the relevant enterprise component that we should be matching the version to @micahlee ?

Hey @izgeri, I'm not entirely sure what you're asking. Would you need/want something more specific than the release version of Conjur Enterprise (e.g. 12.1) that includes the API version?

I imagine there's also a possibility that there would be spec versions for OSS that outpace enterprise releases, such that you could have API spec that is available in a not-yet-released 12.2, for example.

Please let me know if I'm completely misunderstanding the question! 😆

[izgeri]

No, you're on the right track.

@telday I think we might want a mechanism to release the DAP / OSS specs separately ... which maybe starts to point to another mechanism for updating / releasing the DAP spec (probably using release branches like we do in the DAP releases (private) to pick a specific OSS spec release to build a DAP release off of).

So I think we should focus first on building the ability to create OSS spec releases, which will be manual the first time but we should look to have as part of the Conjur OSS release (automated if possible!) going forward.

Then we can start to look at DAP releases of the spec and define the process there.