harbor/api/v2.0/swagger.yaml

667 lines
19 KiB
YAML
Raw Normal View History

swagger: '2.0'
info:
title: Harbor API
description: These APIs provide services for manipulating Harbor project.
version: '2.0'
host: localhost
schemes:
- http
- https
basePath: /api/v2.0
produces:
- application/json
consumes:
- application/json
securityDefinitions:
basicAuth:
type: basic
paths:
/projects/{project_name}/repositories/{repository_name}/artifacts:
get:
summary: List artifacts
description: List artifacts under the specific project and repository.
tags:
- artifact
operationId: listArtifacts
parameters:
- $ref: '#/parameters/requestId'
- $ref: '#/parameters/projectName'
- $ref: '#/parameters/repositoryName'
- $ref: '#/parameters/page'
- $ref: '#/parameters/pageSize'
- name: type
in: query
description: Query the artifacts by type. Valid values can be "IMAGE", "CHART", etc.
type: string
required: false
- name: tags
in: query
description: Without the "tags" query string, both tagged and untagged artifacts will be returned. Specify it as "*" to return only tagged artifacts; specify it as "nil" to return only untagged artifacts.
type: string
required: false
- name: with_tag
in: query
description: Specify whether the tags are inclued inside the returning artifacts
type: boolean
required: false
default: true
- name: with_label
in: query
description: Specify whether the labels are inclued inside the returning artifacts
type: boolean
required: false
default: false
- name: with_scan_overview
in: query
description: Specify whether the scan overview is inclued inside the returning artifacts
type: boolean
required: false
default: false
# should be in tag level
- name: with_signature
in: query
description: Specify whether the signature is inclued inside the returning artifacts
type: boolean
required: false
default: false
- name: with_immutable_status
in: query
description: Specify whether the immutable status is inclued inside the tags of the returning artifacts. Only works when setting "with_tag=true"
type: boolean
required: false
default: false
# TODO add other query string: type, ....
responses:
'200':
description: Success
headers:
X-Total-Count:
description: The total count of artifacts
type: integer
Link:
description: Link refers to the previous page and next page
type: string
schema:
type: array
items:
$ref: '#/definitions/Artifact'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
/projects/{project_name}/repositories/{repository_name}/artifacts/{reference}:
get:
summary: Get the specific artifact
description: Get the artifact specified by the reference under the project and repository. The reference can be digest or tag.
tags:
- artifact
operationId: getArtifact
parameters:
- $ref: '#/parameters/requestId'
- $ref: '#/parameters/projectName'
- $ref: '#/parameters/repositoryName'
- $ref: '#/parameters/reference'
- $ref: '#/parameters/page'
- $ref: '#/parameters/pageSize'
- name: with_tag
in: query
description: Specify whether the tags are inclued inside the returning artifacts
type: boolean
required: false
default: true
- name: with_label
in: query
description: Specify whether the labels are inclued inside the returning artifacts
type: boolean
required: false
default: false
- name: with_scan_overview
in: query
description: Specify whether the scan overview is inclued inside the returning artifacts
type: boolean
required: false
default: false
# should be in tag level
- name: with_signature
in: query
description: Specify whether the signature is inclued inside the returning artifacts
type: boolean
required: false
default: false
- name: with_immutable_status
in: query
description: Specify whether the immutable status is inclued inside the tags of the returning artifacts. Only works when setting "with_tag=true"
type: boolean
required: false
default: false
responses:
'200':
description: Success
schema:
$ref: '#/definitions/Artifact'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
delete:
summary: Delete the specific artifact
description: Delete the artifact specified by the reference under the project and repository. The reference can be digest or tag
tags:
- artifact
operationId: deleteArtifact
parameters:
- $ref: '#/parameters/requestId'
- $ref: '#/parameters/projectName'
- $ref: '#/parameters/repositoryName'
- $ref: '#/parameters/reference'
responses:
'200':
$ref: '#/responses/200'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
/projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/tags:
post:
summary: Create tag
description: Create a tag for the specified artifact
tags:
- artifact
operationId: createTag
parameters:
- $ref: '#/parameters/requestId'
- $ref: '#/parameters/projectName'
- $ref: '#/parameters/repositoryName'
- $ref: '#/parameters/reference'
- name: tag
in: body
description: The JSON object of tag.
required: true
schema:
$ref: '#/definitions/Tag'
responses:
'201':
$ref: '#/responses/201'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'409':
$ref: '#/responses/409'
'500':
$ref: '#/responses/500'
/projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/tags/{tag_name}:
delete:
summary: Delete tag
description: Delete the tag of the specified artifact
tags:
- artifact
operationId: deleteTag
parameters:
- $ref: '#/parameters/requestId'
- $ref: '#/parameters/projectName'
- $ref: '#/parameters/repositoryName'
- $ref: '#/parameters/reference'
- $ref: '#/parameters/tagName'
responses:
'200':
$ref: '#/responses/200'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
/projects/{project_name}/repositories/{repository_name}:
delete:
summary: Delete repository
description: Delete the repository specified by name
tags:
- repository
operationId: deleteRepository
parameters:
- $ref: '#/parameters/requestId'
- $ref: '#/parameters/projectName'
- $ref: '#/parameters/repositoryName'
responses:
'200':
$ref: '#/responses/200'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
/projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/additions/{addition}:
get:
summary: Get the addition of the specific artifact
description: Get the addition of the artifact specified by the reference under the project and repository.
tags:
- artifact
operationId: getAddition
parameters:
- $ref: '#/parameters/requestId'
- $ref: '#/parameters/projectName'
- $ref: '#/parameters/repositoryName'
- $ref: '#/parameters/reference'
- name: addition
in: path
description: The type of addition.
type: string
enum: [build_history, values.yaml, readme, dependencies]
required: true
responses:
'200':
$ref: '#/responses/200'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
/projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/labels:
post:
summary: Add label to artifact
description: Add label to the specified artiact.
tags:
- artifact
operationId: addLabel
parameters:
- $ref: '#/parameters/requestId'
- $ref: '#/parameters/projectName'
- $ref: '#/parameters/repositoryName'
- $ref: '#/parameters/reference'
- name: label
in: body
description: The label that added to the artifact. Only the ID property is needed.
required: true
schema:
$ref: '#/definitions/Label'
responses:
'200':
$ref: '#/responses/200'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'409':
$ref: '#/responses/409'
'500':
$ref: '#/responses/500'
/projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/labels/{label_id}:
delete:
summary: Remove label from artifact
description: Remove the label from the specified artiact.
tags:
- artifact
operationId: removeLabel
parameters:
- $ref: '#/parameters/requestId'
- $ref: '#/parameters/projectName'
- $ref: '#/parameters/repositoryName'
- $ref: '#/parameters/reference'
- name: label_id
in: path
description: The ID of the label that removed from the artifact.
type: integer
format: int64
required: true
responses:
'200':
$ref: '#/responses/200'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'409':
$ref: '#/responses/409'
'500':
$ref: '#/responses/500'
parameters:
requestId:
name: X-Request-Id
description: An unique ID for the request
in: header
type: string
required: false
minLength: 1
projectName:
name: project_name
in: path
description: The name of the project
required: true
type: string
repositoryName:
name: repository_name
in: path
description: The name of the repository
required: true
type: string
reference:
name: reference
in: path
description: The reference of the artifact, can be digest or tag
required: true
type: string
tagName:
name: tag_name
in: path
description: The name of the tag
required: true
type: string
page:
name: page
in: query
type: integer
format: int64
required: false
description: The page number
default: 1
pageSize:
name: page_size
in: query
type: integer
format: int64
required: false
description: The size of per page
default: 10
responses:
'200':
description: Success
headers:
X-Request-Id:
description: The ID of the corresponding request for the response
type: string
'201':
description: Created
headers:
X-Request-Id:
description: The ID of the corresponding request for the response
type: string
'400':
description: Bad request
headers:
X-Request-Id:
description: The ID of the corresponding request for the response
type: string
schema:
$ref: '#/definitions/Errors'
'401':
description: Unauthorized
headers:
X-Request-Id:
description: The ID of the corresponding request for the response
type: string
schema:
$ref: '#/definitions/Errors'
'403':
description: Forbidden
headers:
X-Request-Id:
description: The ID of the corresponding request for the response
type: string
schema:
$ref: '#/definitions/Errors'
'404':
description: Not found
headers:
X-Request-Id:
description: The ID of the corresponding request for the response
type: string
schema:
$ref: '#/definitions/Errors'
'409':
description: Conflict
headers:
X-Request-Id:
description: The ID of the corresponding request for the response
type: string
schema:
$ref: '#/definitions/Errors'
'500':
description: Internal server error
headers:
X-Request-Id:
description: The ID of the corresponding request for the response
type: string
schema:
$ref: '#/definitions/Errors'
definitions:
Errors:
description: The error array that describe the errors got during the handling of request
type: array
items:
$ref: '#/definitions/Error'
Error:
description: a model for all the error response coming from harbor
type: object
properties:
code:
type: string
description: The error code
message:
type: string
description: The error message
Artifact:
type: object
x-go-type:
import:
package: "github.com/goharbor/harbor/src/server/v2.0/handler/model"
type: "Artifact"
properties:
id:
type: integer
format: int64
description: The ID of the artifact
type:
type: string
description: The type of the artifact, e.g. image, chart, etc
media_type:
type: string
description: The media type of the artifact
manifest_media_type:
type: string
description: The manifest media type of the artifact
project_id:
type: integer
format: int64
description: The ID of the project that the artifact belongs to
repository_id:
type: integer
format: int64
description: The ID of the repository that the artifact belongs to
digest:
type: string
description: The digest of the artifact
size:
type: integer
format: int64
description: The size of the artifact
push_time:
type: string
format: date-time
description: The push time of the artifact
pull_time:
type: string
format: date-time
description: The latest pull time of the artifact
extra_attrs:
$ref: '#/definitions/ExtraAttrs'
annotations:
$ref: '#/definitions/Annotations'
references:
type: array
items:
$ref: '#/definitions/Reference'
tags:
type: array
items:
$ref: '#/definitions/Tag'
addition_links:
$ref: '#/definitions/AdditionLinks'
labels:
type: array
items:
$ref: '#/definitions/Label'
Tag:
type: object
properties:
id:
type: integer
format: int64
description: The ID of the tag
repository_id:
type: integer
format: int64
description: The ID of the repository that the tag belongs to
artifact_id:
type: integer
format: int64
description: The ID of the artifact that the tag attached to
name:
type: string
description: The name of the tag
push_time:
type: string
format: date-time
description: The push time of the tag
pull_time:
type: string
format: date-time
description: The latest pull time of the tag
immutable:
type: boolean
x-omitempty: false
description: The immutable status of the tag
signed:
type: boolean
x-omitempty: false
description: The attribute indicates whether the tag is signed or not
ExtraAttrs:
type: object
additionalProperties:
type: object
Annotations:
type: object
additionalProperties:
type: string
AdditionLinks:
type: object
additionalProperties:
$ref: '#/definitions/AdditionLink'
AdditionLink:
type: object
properties:
href:
type: string
description: The link of the addition
absolute:
type: boolean
x-omitempty: false
description: Determine whether the link is an absolute URL or not
Reference:
type: object
properties:
parent_id:
type: integer
format: int64
description: The parent ID of the reference
child_id:
type: integer
format: int64
description: The child ID of the reference
child_digest:
type: string
description: The digest of the child artifact
platform:
$ref: '#/definitions/Platform'
Platform:
type: object
properties:
architecture:
type: string
description: The architecture that the artifact applys to
os:
type: string
description: The OS that the artifact applys to
'''os.version''':
type: string
description: The version of the OS that the artifact applys to
'''os.features''':
type: array
description: The features of the OS that the artifact applys to
items:
type: string
variant:
type: string
description: The variant of the CPU
Label:
type: object
properties:
id:
type: integer
format: int64
description: The ID of the label
name:
type: string
description: The name the label
description:
type: string
description: The description the label
color:
type: string
description: The color the label
scope:
type: string
description: The scope the label
project_id:
type: integer
format: int64
description: The ID of project that the label belongs to
creation_time:
type: string
format: date-time
description: The creation time the label
update_time:
type: string
format: date-time
description: The update time of the label
deleted:
type: boolean
description: Whether the label is deleted or not