generate and publish the OpenAPI 2.0 spec for controller edge-client and management APIs along with each version

[qrkourier]

It would be convenient to be able to reference the current spec for any branch in this repo. I know it's possible to reference the spec already for a deployed controller, but when my question is "What's the current spec for Git ref Z?", then I would prefer to look at that ref in GitHub or my working copy.

[qrkourier]

This might be a good task for me @dovholuknf . It could become a new ziti-ci sub-command and step in the Actions workflow to invoke the build, run the artifact to generate the spec, and commit it before a merge.

[qrkourier]

My priority order would be

1. controller management API
2. controller edge-client API
3. router fabric-transit API
4. router edge-transit API

Please correct my terminology.

[plorenz]

This is a bit tricky. We have the specs, they just live in their respective repos:

• edge client: https://github.com/openziti/edge/blob/main/specs/client.yml
• edge mgmt: https://github.com/openziti/edge/blob/main/specs/management.yml
• fabric mgmt: https://github.com/openziti/fabric/blob/main/specs/swagger.yml

The tricky bit is that you have to know where to find them. I don't think we want to duplicate the specs into the ziti project. Maybe we just want to add a link to the release notes, linking to the versions of the specs based on which versions of fabric and edge are being used?

[dovholuknf]

I'm not sure if it's worth it other than the links provided from @plorenz above. Also these are already available from a running controller so part of me says "just start the controller" for that branch too...

[qrkourier]

@plorenz What if we added a command in ziti CLI to get the different specs by version (if practical) or latest from the proper release refs you linked in GitHub?

[plorenz]

@qrkourier sure, if you think that's useful. The ziti binary has the specs embedded in it, so it could just spit them out. Or it could call out to a server to retrieve them. Retrieving different spec versions would be more complicated. I don't know what's worth it.

[qrkourier]

@plorenz If I understood correctly that means I could get the spec for a particular API version by running the ziti CLI of the same version, after the get spec command is added, that is.

[plorenz]

@plorenz If I understood correctly that means I could get the spec for a particular API version by running the ziti CLI of the same version, after the get spec command is added, that is.

Yes, that should be fairly easy to implement

[qrkourier]

That would occasionally be valuable to me and would spare me the inconvenience of keeping track of the spec links vs spinning up a controller process to get its spec. I'd love to tackle the issue with a little input from you or @dovholuknf or both.

[plorenz]

I don't have any objections if @dovholuknf doesn't

[dovholuknf]

I really would prefer to not have 'one more place' to get the spec from myself...

[qrkourier]

I'll settle for being able to reference the specs in the OZ docs: https://github.com/openziti/ziti-doc/pull/72

[qrkourier]

The Ziti docs still document how to obtain the two main specs from a running instance in https://openziti.github.io/docusaurus/docs/api/rest/, but we decided not to document how to obtain the latest spec from GitHub, in part to avoid confusion about different versions of the spec.