get the edge spec without running an edge API server

openziti / ziti

The parent project for OpenZiti. Here you will find the executables for a fully zero trust, application embedded, programmable network @OpenZiti

https://openziti.io

Apache License 2.0

2.82k stars 159 forks source link

get the edge spec without running an edge API server #625

Closed qrkourier closed 2 years ago

qrkourier commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

My priority order would be

controller management API
controller edge-client API
router fabric-transit API
router edge-transit API

Please correct my terminology.

plorenz commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

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 commented 2 years ago

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

dovholuknf commented 2 years ago

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

qrkourier commented 2 years ago

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

qrkourier commented 2 years ago

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.