From be0ad4a7aa3752412f5472f7d125650b479affb2 Mon Sep 17 00:00:00 2001 From: Lewis Roy Date: Mon, 18 Aug 2025 23:16:18 +1000 Subject: [PATCH] [docs] Refactor Artifact API documentation Add artifact tag to tags.yaml so API docs are ordered correctly (alphabetically with libpod endpoints first). Refactor artifact API documentation to be consistently formated. Refactor some descriptions and summaries to be more accurate and user friendly. Signed-off-by: Lewis Roy --- pkg/api/server/register_artifacts.go | 57 +++++++++++++++------------- pkg/api/tags.yaml | 2 + 2 files changed, 33 insertions(+), 26 deletions(-) diff --git a/pkg/api/server/register_artifacts.go b/pkg/api/server/register_artifacts.go index 86711a94890..a67aba51452 100644 --- a/pkg/api/server/register_artifacts.go +++ b/pkg/api/server/register_artifacts.go @@ -15,13 +15,14 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // tags: // - artifacts // summary: Inspect an artifact - // description: Obtain low-level information about an artifact + // description: | + // Retrieve detailed information about a specific OCI artifact by name or ID. // produces: // - application/json // parameters: // - name: name // in: path - // description: The name or ID of the artifact + // description: Name or ID of the artifact // required: true // type: string // responses: @@ -37,7 +38,7 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // tags: // - artifacts // summary: List artifacts - // description: Returns a list of artifacts on the server. + // description: Return a list of all OCI artifacts in local storage. // produces: // - application/json // responses: @@ -50,8 +51,8 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // --- // tags: // - artifacts - // summary: Pull an OCI artifact - // description: Pulls an artifact from a registry and stores it locally. + // summary: Pull an artifact + // description: Pull an OCI artifact from a remote registry to local storage. // produces: // - application/json // parameters: @@ -72,7 +73,7 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // default: 1s // - name: tlsVerify // in: query - // description: Require TLS verification. + // description: Require TLS verification // type: boolean // default: true // - name: X-Registry-Auth @@ -98,20 +99,22 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // --- // tags: // - artifacts - // summary: Remove one or more Artifacts from local storage. - // description: Remove one or more Artifacts from local storage. + // summary: Remove one or more artifacts + // description: | + // Remove one or more OCI artifacts from local storage. + // Can be filtered by name/ID or all artifacts can be removed. // produces: // - application/json // parameters: // - name: artifacts // in: query - // description: Artifact IDs or names to remove + // description: List of artifact names/IDs to remove // type: array // items: // type: string // - name: all // in: query - // description: Remove all Artifacts + // description: Remove all artifacts // type: boolean // responses: // 200: @@ -125,14 +128,14 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // --- // tags: // - artifacts - // summary: Remove Artifact - // description: Delete an Artifact from local storage + // summary: Remove an artifact + // description: Remove a single artifact from local storage by name or ID. // produces: // - application/json // parameters: // - name: name // in: path - // description: name or ID of artifact to delete + // description: Name or ID of the artifact to remove // required: true // type: string // responses: @@ -147,8 +150,9 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // --- // tags: // - artifacts - // summary: Add an OCI artifact to the local store - // description: Add an OCI artifact to the local store from the local filesystem + // summary: Add a file as an artifact + // description: | + // Add a file as a new OCI artifact, or append to an existing artifact if 'append' is true. // produces: // - application/json // consumes: @@ -161,7 +165,7 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // type: string // - name: fileName // in: query - // description: File to be added to the artifact + // description: Path of the file to be added // required: true // type: string // - name: fileMIMEType @@ -185,7 +189,7 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // default: false // - name: inputStream // in: body - // description: A binary stream of the blob to add to artifact + // description: Binary stream of the file to add to an artifact // schema: // type: string // format: binary @@ -203,8 +207,8 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // --- // tags: // - artifacts - // summary: Push an OCI artifact - // description: Push an OCI artifact from local storage to an image registry. + // summary: Push an artifact + // description: Push an OCI artifact from local storage to a remote image registry. // produces: // - application/json // parameters: @@ -225,7 +229,7 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // default: 1s // - name: tlsVerify // in: query - // description: Require TLS verification. + // description: Require TLS verification // type: boolean // default: true // - name: X-Registry-Auth @@ -251,27 +255,28 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error { // --- // tags: // - artifacts - // summary: Extract an OCI artifact to a local path - // description: Extract the blobs of an OCI artifact to a local file or directory + // summary: Extract an artifacts contents + // description: Extract the files of an OCI artifact to the local filesystem as a tar archive. // produces: // - application/x-tar // parameters: // - name: name // in: path - // description: The name or digest of artifact + // description: Name or digest of the artifact // required: true // type: string // - name: title // in: query - // description: Only extract blob with the given title + // description: Only extract the file with the given title // type: string // - name: digest // in: query - // description: Only extract blob with the given digest + // description: Only extract the file with the given digest // type: string // - name: excludeTitle // in: query - // description: When extracting a single Artifact blob, don't use the blob title as the filename in the tar + // description: | + // When extracting a single file from an artifact, don't use the files title as the file name in the tar archive // type: boolean // responses: // 200: diff --git a/pkg/api/tags.yaml b/pkg/api/tags.yaml index ae29c39a68d..3df18bd88e9 100644 --- a/pkg/api/tags.yaml +++ b/pkg/api/tags.yaml @@ -1,4 +1,6 @@ tags: + - name: artifacts + description: Actions related to artifacts - name: containers description: Actions related to containers - name: exec