diff --git a/docs/swagger.yaml b/docs/swagger.yaml index f32719e19..8edd9043f 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -32,7 +32,6 @@ paths: description: Search parameter for project and repository name. required: true type: string - format: string tags: - Products responses: @@ -55,7 +54,6 @@ paths: description: Project name for filtering results. required: false type: string - format: string - name: is_public in: query description: Public sign for filtering projects. @@ -71,6 +69,8 @@ paths: type: array items: $ref: '#/definitions/Project' + 401: + description: User need to log in first. 500: description: Internal errors. head: @@ -83,7 +83,6 @@ paths: description: Project name for checking exists. required: true type: string - format: string tags: - Products responses: @@ -119,6 +118,31 @@ paths: description: Project name already exists. 500: description: Unexpected internal errors. + /projects/{project_id}: + get: + summary: Return specific project detail infomation + description: | + This endpoint returns specific project information by project ID. + parameters: + - name: project_id + in: path + description: Project ID for filtering results. + required: true + type: integer + format: int64 + tags: + - Products + responses: + 200: + description: Return matched project information. + schema: + type: array + items: + $ref: '#/definitions/Project' + 401: + description: User need to log in first. + 500: + description: Internal errors. /projects/{project_id}/publicity: put: summary: Update properties for a selected project. @@ -128,7 +152,7 @@ paths: - name: project_id in: path type: integer - format: int32 + format: int64 required: true description: Selected project ID. - name: project @@ -161,7 +185,7 @@ paths: - name: project_id in: path type: integer - format: int32 + format: int64 required: true description: Relevant project ID - name: access_log @@ -193,7 +217,7 @@ paths: - name: project_id in: path type: integer - format: int32 + format: int64 required: true description: Relevant project ID. tags: @@ -223,7 +247,7 @@ paths: - name: project_id in: path type: integer - format: int32 + format: int64 required: true description: Relevant project ID. - name: roles @@ -257,13 +281,13 @@ paths: - name: project_id in: path type: integer - format: int32 + format: int64 required: true description: Relevant project ID - name: user_id in: path type: integer - format: int32 + format: int required: true description: Relevant user ID tags: @@ -293,13 +317,13 @@ paths: - name: project_id in: path type: integer - format: int32 + format: int64 required: true description: Relevant project ID. - name: user_id in: path type: integer - format: int32 + format: int required: true description: Relevant user ID. - name: roles @@ -330,13 +354,13 @@ paths: - name: project_id in: path type: integer - format: int32 + format: int64 required: true description: Relevant project ID. - name: user_id in: path type: integer - format: int32 + format: int required: true description: Relevant user ID. tags: @@ -377,10 +401,9 @@ paths: description: | This endpoint is for user to search registered users, support for filtering results with username.Notice, by now this operation is only for administrator. parameters: - - name: user_name + - name: username in: query type: string - format: string required: false description: Username for filtering results. tags: @@ -431,7 +454,7 @@ paths: - name: user_id in: path type: integer - format: int32 + format: int required: true description: Registered user ID - name: profile @@ -464,7 +487,7 @@ paths: - name: user_id in: path type: integer - format: int32 + format: int required: true description: User ID for marking as to be removed. tags: @@ -491,7 +514,7 @@ paths: - name: user_id in: path type: integer - format: int32 + format: int required: true description: Registered user ID. - name: password @@ -508,9 +531,9 @@ paths: 400: description: Invalid user ID; Old password is blank; New password is blank. 401: - description: Old password is not correct. + description: Don't have authority to change password. Please check login status. 403: - description: Guests can only change their own account. + description: Old password is not correct. 500: description: Unexpected internal errors. /users/{user_id}/sysadmin: @@ -523,7 +546,7 @@ paths: - name: user_id in: path type: integer - format: int32 + format: int required: true description: Registered user ID tags: @@ -556,7 +579,6 @@ paths: - name: q in: query type: string - format: string required: false description: Repo name for filtering results. tags: @@ -584,13 +606,11 @@ paths: - name: repo_name in: query type: string - format: string required: true description: The name of repository which will be deleted. - name: tag in: query type: string - format: string required: false description: Tag of a repository. tags: @@ -645,6 +665,10 @@ paths: responses: 200: description: Retrieved manifests from a relevant repository successfully. + schema: + $ref: '#/definitions/Repository' + 404: + description: Retrieved manifests from a relevant repository not found. 500: description: Unexpected internal errors. /repositories/top: @@ -711,6 +735,437 @@ paths: description: User need to login first. 500: description: Unexpected internal errors. + /jobs/replication: + get: + summary: List filters jobs according to the policy and repository + description: | + This endpoint let user list filters jobs according to the policy and repository. (if start_time and end_time are both null, list jobs of last 10 days) + tags: + - Products + parameters: + - name: policy_id + in: query + type: integer + format: int + required: false + description: The ID of the policy that triggered this job. + - name: num + in: query + type: integer + format: int32 + required: false + description: The return list length number. + - name: end_time + in: query + type: integer + format: int64 + required: false + description: The end time of jobs done. (Timestamp) + - name: start_time + in: query + type: integer + format: int64 + required: false + description: The start time of jobs. (Timestamp) + - name: repository + in: query + type: string + required: false + description: The respond jobs list filter by repository name. + - name: status + in: query + type: string + required: false + description: The respond jobs list filter by status. + responses: + 200: + description: Get the required logs successfully. + schema: + type: array + items: + $ref: '#/definitions/JobStatus' + 400: + description: Bad request because of invalid parameters. + 401: + description: User need to login first. + 500: + description: Unexpected internal errors. + /jobs/replication/{id}: + delete: + summary: Delete specific ID job. + description: | + This endpoint is aimed to remove specific ID job from jobservice. + parameters: + - name: id + in: path + type: integer + format: int64 + required: true + description: Delete job ID. + tags: + - Products + responses: + 200: + description: Job deleted successfully. + 400: + description: Job ID is invalid or can't remove this job. + 401: + description: Only admin has this authority. + 404: + description: Project ID does not exist. + 500: + description: Unexpected internal errors. + /jobs/replication/{repo_id}/log: + get: + summary: Get job logs accompany with a relevant repository. + description: | + This endpoint let user search job logs filtered by repository ID. + parameters: + - name: repo_id + in: path + type: integer + format: int64 + required: true + description: Relevant repository ID + tags: + - Products + responses: + 200: + description: Get job log successfully. + 400: + description: Illegal format of provided ID value. + 401: + description: User need to log in first. + 404: + description: The specific repository ID's log does not exist. + 500: + description: Unexpected internal errors. + /policies/replication: + get: + summary: List filters policies by name and project_id + description: | + This endpoint let user list filters policies by name and project_id, if name and project_id are nil, list returns all policies + parameters: + - name: name + in: query + type: string + required: false + description: The replication's policy name. + - name: project_id + in: query + type: integer + format: int64 + required: false + description: Relevant project ID. + tags: + - Products + responses: + 200: + description: Get policy successfully. + schema: + type: array + items: + $ref: '#/definitions/JobStatus' + 400: + description: Invalid project ID. + 401: + description: User need to log in first. + 500: + description: Unexpected internal errors. + post: + summary: Post creates a policy + description: | + This endpoint let user creates a policy, and if it is enabled, the replication will be triggered right now. + parameters: + - name: policyinfo + in: body + description: Create new policy. + required: true + schema: + $ref: '#/definitions/RepPolicyPost' + tags: + - Products + responses: + 201: + description: Create policy successfully. + 400: + description: Invalid project ID or target ID. + 401: + description: User need to log in first. + 409: + description: Policy name already used or policy already exists with the same project and target. + 500: + description: Unexpected internal errors. + /policies/replication/{repo_id}: + get: + summary: Get replication policy accompany with a relevant repository. + description: | + This endpoint let user search replication policy by repository ID. + parameters: + - name: repo_id + in: path + type: integer + format: int64 + required: true + description: Relevant repository ID + tags: + - Products + responses: + 200: + description: Get job policy successfully. + schema: + $ref: '#/definitions/RepPolicy' + 401: + description: User need to log in first. + 404: + description: The specific repository ID's policy does not exist. + 500: + description: Unexpected internal errors. + put: + summary: Put modifies name, description, target and enablement of policy. + description: | + This endpoint let user update policy name, description, target and enablement. + parameters: + - name: repo_id + in: path + type: integer + format: int64 + required: true + description: Relevant repository ID + - name: policyupdate + in: body + description: Update policy name, description, target and enablement. + required: true + schema: + $ref: '#/definitions/RepPolicyUpdate' + tags: + - Products + responses: + 200: + description: Update job policy content successfully. + 400: + description: policy is enabled or target does not exist + 401: + description: User need to log in first. + 404: + description: The specific repository ID's policy does not exist. + 409: + description: Policy name already used or policy already exists with the same project and target. + 500: + description: Unexpected internal errors. + /policies/replication/{repo_id}/enablement: + put: + summary: Put modifies enablement of the policy. + description: | + This endpoint let user update policy enablement flag. + parameters: + - name: repo_id + in: path + type: integer + format: int64 + required: true + description: Relevant repository ID + - name: enabledflag + in: body + description: The policy enablement flag. + required: true + schema: + $ref: '#/definitions/RepPolicyEnablementReq' + tags: + - Products + responses: + 200: + description: Update job policy enablement successfully. + 400: + description: Invalid enabled value. + 401: + description: User need to log in first. + 404: + description: The specific repository ID's policy does not exist. + 500: + description: Unexpected internal errors. + /targets: + get: + summary: List filters targets by name. + description: | + This endpoint let user list filters targets by name, if name is nil, list returns all targets. + parameters: + - name: name + in: query + type: string + required: false + description: The replication's target name. + tags: + - Products + responses: + 200: + description: Get policy successfully. + schema: + type: array + items: + $ref: '#/definitions/RepTarget' + 401: + description: User need to log in first. + 500: + description: Unexpected internal errors. + post: + summary: Create a new replication target. + description: | + This endpoint is for user to create a new replication target. + parameters: + - name: reptarget + in: body + description: New created replication target. + required: true + schema: + $ref: '#/definitions/RepTargetPost' + tags: + - Products + responses: + 201: + description: Replication target created successfully. + 400: + description: Unsatisfied with constraints of the target creation. + 401: + description: User need to log in first. + 409: + description: Replication target name already exists. + 500: + description: Unexpected internal errors. + /targets/ping: + post: + summary: Ping validates target. + description: | + This endpoint is for ping validates whether the target is reachable and whether the credential is valid. + parameters: + - name: id + in: query + type: integer + format: int64 + required: false + description: The replication's policy ID. + tags: + - Products + responses: + 200: + description: Ping target successfully. + 400: + description: Target id is invalid/ endpoint is needed/ invaild URL/ network issue. + 401: + description: User need to log in first or wrong username/password for remote target. + 404: + description: Target not found. + 500: + description: Unexpected internal errors. + /targets/{repo_id}: + put: + summary: Update replication's target. + description: | + This endpoint is for update specific replication's target. + parameters: + - name: repo_id + in: path + type: integer + format: int64 + required: true + description: The replication's target ID. + - name: repo_target + in: body + required: true + schema: + $ref: '#/definitions/RepTargetPost' + description: Updates of replication's target. + tags: + - Products + responses: + 200: + description: Updated replication's target successfully. + 400: + description: The target is associated with policy which is enabled. + 401: + description: User need to log in first. + 404: + description: Target ID does not exist. + 409: + description: Target name or endpoint is already used. + 500: + description: Unexpected internal errors. + get: + summary: Get replication's target. + description: This endpoint is for get specific replication's target. + tags: + - Products + parameters: + - name: repo_id + in: path + type: integer + format: int64 + required: true + description: The replication's target ID. + responses: + 200: + description: Get replication's target successfully. + schema: + type: array + items: + $ref: '#/definitions/RepTarget' + 401: + description: User need to log in first. + 404: + description: Replication's target not found + 500: + description: Unexpected internal errors. + delete: + summary: Delete specific replication's target. + description: | + This endpoint is for to delete specific replication's target. + parameters: + - name: repo_id + in: path + type: integer + format: int64 + required: true + description: The replication's target ID. + tags: + - Products + responses: + 200: + description: Replication's target deleted successfully. + 400: + description: Replication's target ID is invalid or the target is used by policies. + 401: + description: Only admin has this authority. + 404: + description: Replication's target does not exist. + 500: + description: Unexpected internal errors. + /targets/{repo_id}/policies/: + get: + summary: List the target relevant policies. + description: | + This endpoint list policies filter with specific replication's target ID. + parameters: + - name: repo_id + in: path + type: integer + format: int64 + required: true + description: The replication's target ID. + tags: + - Products + responses: + 200: + description: Get relevant policies successfully. + schema: + type: array + items: + $ref: '#/definitions/RepPolicy' + 401: + description: User need to log in first. + 404: + description: Replication's target not found + 500: + description: Unexpected internal errors. definitions: Search: type: object @@ -798,6 +1253,33 @@ definitions: repo_count: type: integer description: The number of the repositories under this project. + Repository: + type: object + properties: + id: + type: string + description: Repository ID + parent: + type: string + description: Parent of the image. + created: + type: string + description: Repository create time. + duration_days: + type: string + description: Duration days of the image. + author: + type: string + description: Author of the image. + architecture: + type: string + description: Architecture of the image. + docker_version: + type: string + description: Docker version of the image. + os: + type: string + description: OS of the image. User: type: object properties: @@ -924,4 +1406,171 @@ definitions: type: integer format: int32 description: The count of the total repositories, only be seen when the user is admin. - + JobStatus: + type: object + properties: + id: + type: integer + format: int64 + description: The job ID. + status: + type: string + description: The status of the job. + repository: + type: string + description: The repository handled by the job. + policy_id: + type: integer + format: int64 + description: The ID of the policy that triggered this job. + operation: + type: string + description: The operation of the job. + tags: + type: array + description: The repository's used tag list. + items: + $ref: '#/definitions/Tags' + creation_time: + type: string + description: The creation time of the job. + update_time: + type: string + description: The update time of the job. + Tags: + type: object + properties: + tag: + type: string + description: The repository's used tag. + RepPolicy: + type: object + properties: + id: + type: integer + format: int64 + description: The policy ID. + project_id: + type: integer + format: int64 + description: The project ID. + project_name: + type: string + description: The project name. + target_id: + type: integer + format: int64 + description: The target ID. + target_name: + type: string + description: The target name. + name: + type: string + description: The policy name. + enabled: + type: integer + format: int + description: The policy's enabled status. + description: + type: string + description: The description of the policy. + cron_str: + type: string + description: The cron string for schedule job. + start_time: + type: string + description: The start time of the policy. + creation_time: + type: string + description: The create time of the policy. + update_time: + type: string + description: The update time of the policy. + error_job_count: + format: int + description: The error job count number for the policy. + RepPolicyPost: + type: object + properties: + project_id: + type: integer + format: int64 + description: The project ID. + target_id: + type: integer + format: int64 + description: The target ID. + name: + type: string + description: The policy name. + RepPolicyUpdate: + type: object + properties: + target_id: + type: integer + format: int64 + description: The target ID. + name: + type: string + description: The policy name. + enabled: + type: integer + format: int + description: The policy's enabled status. + description: + type: string + description: The description of the policy. + cron_str: + type: string + description: The cron string for schedule job. + RepPolicyEnablementReq: + type: object + properties: + enabled: + type: integer + format: int + description: The policy enablement flag. + RepTarget: + type: object + properties: + id: + type: integer + format: int64 + description: The target ID. + endpoint: + type: string + description: The target address URL string. + name: + type: string + description: The target name. + username: + type: string + description: The target server username. + password: + type: string + description: The target server password. + type: + type: integer + format: int + description: Reserved field. + creation_time: + type: string + description: The create time of the policy. + update_time: + type: string + description: The update time of the policy. + RepTargetPost: + type: object + properties: + endpoint: + type: string + description: The target address URL string. + name: + type: string + description: The target name. + username: + type: string + description: The target server username. + password: + type: string + description: The target server password.