Add some documentation to packages (#21648)

In #21637 it was mentioned that the purpose of the API routes for the
packages is unclear. This PR adds some documentation.

Fix #21637

Signed-off-by: Andrew Thornton <art27@cantab.net>
Co-authored-by: KN4CK3R <admin@oldschoolhack.me>
This commit is contained in:
zeripath 2022-11-12 18:59:15 +00:00 committed by GitHub
parent 158b088ec3
commit a0a425a13b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 14 additions and 2 deletions

View file

@ -40,7 +40,9 @@ func reqPackageAccess(accessMode perm.AccessMode) func(ctx *context.Context) {
} }
} }
func Routes(ctx gocontext.Context) *web.Route { // CommonRoutes provide endpoints for most package managers (except containers - see below)
// These are mounted on `/api/packages` (not `/api/v1/packages`)
func CommonRoutes(ctx gocontext.Context) *web.Route {
r := web.NewRoute() r := web.NewRoute()
r.Use(context.PackageContexter(ctx)) r.Use(context.PackageContexter(ctx))
@ -301,6 +303,9 @@ func Routes(ctx gocontext.Context) *web.Route {
return r return r
} }
// ContainerRoutes provides endpoints that implement the OCI API to serve containers
// These have to be mounted on `/v2/...` to comply with the OCI spec:
// https://github.com/opencontainers/distribution-spec/blob/main/spec.md
func ContainerRoutes(ctx gocontext.Context) *web.Route { func ContainerRoutes(ctx gocontext.Context) *web.Route {
r := web.NewRoute() r := web.NewRoute()

View file

@ -1073,6 +1073,7 @@ func Routes(ctx gocontext.Context) *web.Route {
}, repoAssignment()) }, repoAssignment())
}) })
// NOTE: these are Gitea package management API - see packages.CommonRoutes and packages.DockerContainerRoutes for endpoints that implement package manager APIs
m.Group("/packages/{username}", func() { m.Group("/packages/{username}", func() {
m.Group("/{type}/{name}/{version}", func() { m.Group("/{type}/{name}/{version}", func() {
m.Get("", packages.GetPackage) m.Get("", packages.GetPackage)

View file

@ -185,8 +185,14 @@ func NormalRoutes(ctx context.Context) *web.Route {
r.Mount("/", web_routers.Routes(ctx)) r.Mount("/", web_routers.Routes(ctx))
r.Mount("/api/v1", apiv1.Routes(ctx)) r.Mount("/api/v1", apiv1.Routes(ctx))
r.Mount("/api/internal", private.Routes()) r.Mount("/api/internal", private.Routes())
if setting.Packages.Enabled { if setting.Packages.Enabled {
r.Mount("/api/packages", packages_router.Routes(ctx)) // Add endpoints to match common package manager APIs
// This implements package support for most package managers
r.Mount("/api/packages", packages_router.CommonRoutes(ctx))
// This implements the OCI API (Note this is not preceded by /api but is instead /v2)
r.Mount("/v2", packages_router.ContainerRoutes(ctx)) r.Mount("/v2", packages_router.ContainerRoutes(ctx))
} }
return r return r