[Feat]: Document zot endpoints in the developer guide

[andaaron]

Is your feature request related to a problem? Please describe.

Right now it is not trivial to identify all http endpoints currently exposed by zot.
Let's add the list to the zot developer guide.

/ (ui) - enabled by using the ui build label and having the ui extension configuration enabled
/auth/login - available when OpenID authentication is enabled
/auth/logout - available when authentication is available in general (not just for OpenID, but all session-based authentication)
/auth/apikey - available when API key authentication is enabled
/auth/callback - available when OpenID authentication is enabled
/oras/artifacts/v1/ (oras) - always enabled
/metrics (metrics with extensions) - when the metrics build label is used and the metrics extension is enabled
/swagger/v2/ (swagger) - enabled by using the the debug build label
/v2/ (oci spec specific endpoints) - always available
/v2/_oci/ext/discover (discover extensions per oci spec) - always available
/v2/metrics (metrics without extensions) - when metrics extension is disabled, regardless if the metrics build label was used or not
/v2/_zot/ext/mgmt (mgmt extension) - enabled by using the mgmt build label and having both the search and the ui extensions configurations enabled.
/v2/_zot/ext/cosign (imagetrust extension) - enabled by using the imagetrust build label and having the trust extension configuration enabled with the cosign option enabled
/v2/_zot/ext/notation (imagetrust extension, will have query parameters for uploading certificates for signature verification) - enabled by using the imagetrust build label and having the trust extension configuration enabled with the notation option enabled
/v2/_zot/ext/search (search extension) - enabled by using the search build label and having the search extension configuration enabled
/v2/_zot/ext/userprefs (user preferences extension) - enabled by using the userprefs build label and having both the search and the ui extensions configurations enabled.
/v2/_zot/debug/graphql-playground (graphql playground) - enabled by using the the debug build label

Describe the solution you'd like

We should have an article about these endpoints and how to build/enable them.

Describe alternatives you've considered

We could potentially have separate articles per feature - I don't think they are all covered at the moment.

Additional context

No response

[mbshields]

Should we have an API guide reference article, like we have with zli? Or is there (should there be) a Swagger document for this?

[andaaron]

There is a swagger document, but it doesn't cover all endpoints. Looking at the endpoint list, the ones below are missing from swagger:

/ (ui) - enabled by using the ui build label and having the ui extension configuration enabled
/auth/login - available when OpenID authentication is enabled
/auth/callback - available when OpenID authentication is enabled
/metrics (metrics with extensions) - when the metrics build label is used and the metrics extension is enabled
/swagger/v2/ (swagger) - enabled by using the the debug build label
/v2/metrics (metrics without extensions) - when metrics extension is disabled, regardless if the metrics build label was used or not
/v2/_zot/ext/search (search extension) - enabled by using the search build label and having the search extension configuration enabled
/v2/_zot/debug/graphql-playground (graphql playground) - enabled by using the the debug build label

Actually /auth/login and /auth/callback we should add there. Not sure about the rest, @rchincha?

In any case, the swagger document does not include any information about which of these may or may not be built into the running zot binary, and does not include how to enable them in the config, if required.

[andaaron]

Note /v2/metrics is gone, there is only /metrics now, for both internal implementation and Prometheus. The route returns different data depending on whether or not the metrics build label was used.

There's also the profiling endpoint to include in the list, but there's a separate issue for that.