Add list tags and get tag endpoints OpenAPI documentation

docker-hub/api/latest.yaml

@@ -820,67 +820,62 @@ paths:
           $ref: "#/components/responses/Forbidden"
         404:
           $ref: "#/components/responses/NotFound"
-  /v2/repositories/{namespace}/{repository}/:
+          
+
+  /v2/namespace/{namespace}/repositories/{repository}/tags:
     parameters:
-      - name: namespace
+      - $ref: "#/components/parameters/namespace"
-        in: path
+      - $ref: "#/components/parameters/repository"
-        required: true
+    get:
-        description: Namespace of the repository.
+      summary: "List repository tags"
-        schema:
+      tags: [ repositories ]
-          type: string
+      parameters:
-      - name: repository
+        - $ref: "#/components/parameters/page"
-        in: path
+        - $ref: "#/components/parameters/page_size"
-        required: true
-        description: Name of the repository.
-        schema:
-          type: string
-    patch:
-      tags:
-        - repositories
-      summary: Update repository configuration
-      description: |
-        Update the configuration of a repository:
-
-        - description: the summary of a repository
-        - full description: the readme displayed on repository's page, markdown accepted
-        - visibility: is the repository public or private
-
-        Authentication is required.
-      operationId: PatchRepositoryDescription
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/update_repository"
       responses:
         200:
-          description: Success
+          $ref: "#/components/responses/list_tags"
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/repository"
         403:
-          description:
+          $ref: "#/components/responses/Forbidden"
-            Forbidden - access to the resource is forbidden, you don't have
-            needed permission to perform this action.
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorDetail"
-              examples:
-                response:
-                  value:
-                    detail: You do not have permission to perform this action.
         404:
-          description: Repository not found or unable to access the resource
+          $ref: "#/components/responses/NotFound"
-          content:
+    head:
-            application/json:
+      summary: "Check repository tags"
-              schema:
+      tags: [ repositories ]
-                $ref: "#/components/schemas/ErrorDetail"
+      responses:
-              examples:
+        200:
-                response:
+          description: "Repository contains tags"
-                  value:
+        403:
-                    detail: Object not found
+          $ref: "#/components/responses/Forbidden"
+        404:
+          $ref: "#/components/responses/NotFound"
+
+  /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}:
+    parameters:
+      - $ref: "#/components/parameters/namespace"
+      - $ref: "#/components/parameters/repository"
+      - $ref: "#/components/parameters/tag"
+    get:
+      summary: "Read repository tag"
+      tags: [ repositories ]
+      responses:
+        200:
+          $ref: "#/components/responses/get_tag"
+        403:
+          $ref: "#/components/responses/Forbidden"
+        404:
+          $ref: "#/components/responses/NotFound"
+    head:
+      summary: "Check repository tag"
+      tags: [ repositories ]
+      responses:
+        200:
+          description: "Repository tag exists"
+        403:
+          $ref: "#/components/responses/Forbidden"
+        404:
+          $ref: "#/components/responses/NotFound"
+
 
   /v2/scim/2.0/ServiceProviderConfig:
     get:
@@ -1342,6 +1337,20 @@ components:
         application/scim+json:
           schema:
             $ref: "#/components/schemas/scim_user"
+            
+    list_tags:
+      description: "list repository tags"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/paginated_tags"
+            
+    get_tag:
+      description: "repository tag"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/tag"
 
   schemas:
     UsersLoginRequest:
@@ -1997,68 +2006,138 @@ components:
           type: boolean
           description: Allow usage of verified publisher images if "enabled" is `true`.
           example: true
-    update_repository:
+    layer:
       type: object
       properties:
-        description:
+        digest:
           type: string
-          description:
+          description: "image layer digest"
-            The description of a repository, as displayed below the repository
+          nullable: true
-            name.
+        size:
-          example: Hello World! (an example of minimal Dockerization)
+          type: integer
-        full_description:
+          description: "size of the layer"
+        instruction:
           type: string
-          description:
+          description: "Dockerfile instruction"
-            The full description displayed on the repository page. Markdown
+    image:
-            accepted.
-          example: |
-            # Quick reference
-            - Maintained by: [the Docker Community](https://github.com/docker-library/hello-world)
-            
-            # Example output
-            ```
-            $ docker run hello-world
-
-            Hello from Docker!
-            This message shows that your installation appears to be working correctly.
-            ```
-    repository:
       type: object
       properties:
-        name:
+        architecture:
           type: string
-          description: name of the repository
+          description: "CPU architecture"
-          example: hello-world
+        features:
-        namespace:
           type: string
-          description: namespace of the repository
+          description: "CPU features"
-          example: docker
+        variant:
-        description:
           type: string
-          description: short description of the repository
+          description: "CPU variant"
-          example: Hello World! (an example of minimal Dockerization)
+        digest:
-        is_private:
+          type: string
-          type: boolean
+          description: "image digest"
-          description: visibility of the repository
+          nullable: true
-          example: true
+        layers:
+          type: array
+          items:
+            $ref: '#/components/schemas/layer'
+        os:
+          type: string
+          description: "operating system"
+        os_features:
+          type: string
+          description: "OS features"
+        os_version:
+          type: string
+          description: "OS version"
+        size:
+          type: integer
+          description: "size of the image"
+        status:
+          type: string
+          enum: ["active", "inactive"]
+          description: "Status of the image"
+        last_pulled:
+          type: string
+          example: "2021-01-05T21:06:53.506400Z"
+          description: "datetime of last pull"
+          nullable: true
+        last_pushed:
+          type: string
+          example: "2021-01-05T21:06:53.506400Z"
+          description: "datetime of last push"
+          nullable: true
+    tag:
+      type: object
+      properties:
+        id:
+          type: integer
+          description: "tag ID"
+        images:
+          type: object
+          $ref: '#/components/schemas/image'
+        creator:
+          type: integer
+          description: "ID of the user that pushed the tag"
         last_updated:
           type: string
-          example: 2020-04-22T09:47:28.119596Z
+          example: "2021-01-05T21:06:53.506400Z"
-        full_description:
+          description: "datetime of last update"
+          nullable: true
+        last_updater:
+          type: integer
+          description: "ID of the last user that updated the tag"
+        last_updater_username:
           type: string
-          description: Description (readme) of the repository, in Markdown
+          description: "Hub username of the user that updated the tag"
-          example: |
+        name:
-            # Quick reference 
+          type: string
+          description: "name of the tag"
+        repository:
+          type: integer
+          description: "repository ID"
+        full_size:
+          type: integer
+          description: "compressed size (sum of all layers) of the tagged image"
+        v2:
+          type: string
+          description: "repository API version"
+        status:
+          type: string
+          enum: ["active", "inactive"]
+          description: "whether a tag has been pushed to or pulled in the past month"
+        tag_last_pulled:
+          type: string
+          example: "2021-01-05T21:06:53.506400Z"
+          description: "datetime of last pull"
+          nullable: true
+        tag_last_pushed:
+          type: string
+          example: "2021-01-05T21:06:53.506400Z"
+          description: "datetime of last push"
+          nullable: true
 
-            - Maintained by: [the Docker Community](https://github.com/docker-library/hello-world)
+    paginated_tags:
-
+      allOf:
-            # Example output
+        - $ref: '#/components/schemas/page'
-            ```
+        - type: object
-            $ docker run hello-world
+          properties:
-
+            results:
-            Hello from Docker!
+              type: array
-            This message shows that your installation appears to be working correctly.
+              items:
-            ```
+                $ref: '#/components/schemas/tag'
+    page:
+      type: object
+      properties:
+        count:
+          type: integer
+          description: total number of results available across all pages
+        next:
+          type: string
+          description: link to next page of results if any
+          nullable: true
+        previous:
+          type: string
+          description: link to previous page of results  if any
+          nullable: true
 
     scim_error:
       type: object
@@ -2352,6 +2431,38 @@ components:
         type: string
       description: The user ID.
       example: "d80f7c79-7730-49d8-9a41-7c42fb622d9c"
+    namespace:
+      in: path
+      name: namespace
+      required: true
+      schema:
+        type: string
+    repository:
+      in: path
+      name: repository
+      required: true
+      schema:
+        type: string
+    tag:
+      in: path
+      name: tag
+      required: true
+      schema:
+        type: string
+    page:
+      in: query
+      name: page
+      required: false
+      schema:
+        type: integer
+      description: "Page number to get. Defaults to 1."
+    page_size:
+      in: query
+      name: page_size
+      required: false
+      schema:
+        type: integer
+      description: "Number of images to get per page. Defaults to 10. Max of 1000."
 
   requestBodies:
     scim_create_user_request: