docs(api): clarify swagger-only image descriptor wrapper

Agent-Logs-Url: https://github.com/project-zot/zot/sessions/5d32009a-59ed-4867-a7d3-39758c16a090

Co-authored-by: rchincha <45800463+rchincha@users.noreply.github.com>

pkg/api/routes.go

@@ -602,6 +602,8 @@ type ImageIndex struct {
 	Annotations  map[string]string `json:"annotations,omitempty"`
 }
 
+// ImageDescriptor is a swagger-friendly variant of ispec.Descriptor.
+// It keeps digest as string to avoid swagger parser issues with external digest.Digest.
 type ImageDescriptor struct {
 	MediaType    string            `json:"mediaType"`
 	Digest       string            `json:"digest"`

swagger/docs.go

@@ -1264,7 +1264,7 @@ const docTemplate = `{
                     "type": "string"
                 },
                 "platform": {
-                    "$ref": "#/definitions/v1.Platform"
+                    "$ref": "#/definitions/github_com_opencontainers_image-spec_specs-go_v1.Platform"
                 },
                 "size": {
                     "type": "integer"
@@ -1481,7 +1481,7 @@ const docTemplate = `{
                 }
             }
         },
-        "v1.Platform": {
+        "github_com_opencontainers_image-spec_specs-go_v1.Platform": {
             "type": "object",
             "properties": {
                 "architecture": {

swagger/swagger.json

@@ -1256,7 +1256,7 @@
                     "type": "string"
                 },
                 "platform": {
-                    "$ref": "#/definitions/v1.Platform"
+                    "$ref": "#/definitions/github_com_opencontainers_image-spec_specs-go_v1.Platform"
                 },
                 "size": {
                     "type": "integer"
@@ -1473,7 +1473,7 @@
                 }
             }
         },
-        "v1.Platform": {
+        "github_com_opencontainers_image-spec_specs-go_v1.Platform": {
             "type": "object",
             "properties": {
                 "architecture": {

swagger/swagger.yaml

@@ -34,7 +34,7 @@ definitions:
       mediaType:
         type: string
       platform:
-        $ref: '#/definitions/v1.Platform'
+        $ref: '#/definitions/github_com_opencontainers_image-spec_specs-go_v1.Platform'
       size:
         type: integer
       urls:
@@ -174,7 +174,7 @@ definitions:
       releaseTag:
         type: string
     type: object
-  v1.Platform:
+  github_com_opencontainers_image-spec_specs-go_v1.Platform:
     properties:
       architecture:
         description: |-