From 117dfca0fc5d9ff08c46fbd1742e331ddda58ef4 Mon Sep 17 00:00:00 2001 From: Yves Brissaud Date: Wed, 9 Mar 2022 17:21:48 +0100 Subject: [PATCH] add endpoint to edit repository (#14324) * add endpoint to edit a repository configuration User can edit: - description - full description (readme) - visibility (public or private) Also added needed route to be able to login using a 2FA. Signed-off-by: Yves Brissaud * rename repository tag to repositories Signed-off-by: Yves Brissaud * improve the examples and 404 on edit repo Signed-off-by: Yves Brissaud --- docker-hub/api/latest.yaml | 180 ++++++++++++++++++++++++++++++++++++- 1 file changed, 177 insertions(+), 3 deletions(-) diff --git a/docker-hub/api/latest.yaml b/docker-hub/api/latest.yaml index 05bc0a707a..fa7a89ef8c 100644 --- a/docker-hub/api/latest.yaml +++ b/docker-hub/api/latest.yaml @@ -94,6 +94,10 @@ tags: x-displayName: Org Settings description: | The Org Settings API endpoints allow you to manage your organization's settings. + - name: repositories + x-displayName: Repositories + description: | + The repository endpoints allow you to manage your repository's configuration like description. x-tagGroups: - name: General @@ -107,6 +111,7 @@ x-tagGroups: - images - audit-logs - org-settings + - repositories definitions: UsersLoginRequest: @@ -134,10 +139,39 @@ definitions: x-nullable: false example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c PostUsersLoginErrorResponse: - description: failed user login response. + description: failed user login response or second factor required + type: object + required: + - detail + properties: + detail: + description: Description of the error. + type: string + x-nullable: false + example: Incorrect authentication credentials + login_2fa_token: + description: Short time lived token to be used on `/v2/users/2fa-login` to complete the authentication. This field is present only if 2FA is enabled. + type: string + x-nullable: true + example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + Users2FALoginRequest: + description: Second factor user login details + type: object + required: [ login_2fa_token, code ] + properties: + login_2fa_token: + description: The intermediate 2FA token returned from `/v2/users/login` API. + type: string + example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + code: + description: The Time-based One-Time Password of the Docker Hub account to authenticate with. + type: string + example: 123456 + PostUsers2FALoginErrorResponse: + description: failed second factor login response. type: object properties: - details: + detail: description: Description of the error. type: string x-nullable: false @@ -170,6 +204,13 @@ definitions: type: string errinfo: $ref: '#/definitions/ErrorInfo' + ErrorDetail: + description: Error with a detail field. + type: object + properties: + detail: + description: The error message. + type: string GetNamespaceRepositoryImagesSummaryResponse: description: Summary information for images in a repository. type: object @@ -682,6 +723,61 @@ definitions: description: Allow usage of verified publisher images if "enabled" is `true`. example: true + update_repository: + type: object + properties: + description: + type: string + description: The description of a repository, as displayed below the repository name. + example: Hello World! (an example of minimal Dockerization) + full_description: + type: string + description: The full description displayed on the repository page. Markdown 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. + ``` + is_private: + type: boolean + description: Allow to change visibility of the repository. + example: true + + repository: + type: object + properties: + name: + type: string + description: name of the repository + example: hello-world + namespace: + type: string + description: namespace of the repository + example: docker + description: + type: string + description: short description of the repository + example: "Hello World! (an example of minimal Dockerization)" + is_private: + type: boolean + description: visibility of the repository + example: true + last_updated: + type: string + example: "2020-04-22T09:47:28.119596Z" + full_description: + type: string + description: Description (readme) of the repository, in Markdown + example: "# Quick reference \n\n* Maintained by: [the Docker Community](https://github.com/docker-library/hello-world)\n\n# Example output\n\n```\n$ docker run hello-world\n\n\nHello from Docker!\nThis message shows that your installation appears to be working correctly.\n```" + paths: /v2/users/login: post: @@ -707,9 +803,38 @@ paths: schema: $ref: '#/definitions/PostUsersLoginSuccessResponse' 401: - description: Authentication failed + description: Authentication failed or second factor required schema: $ref: '#/definitions/PostUsersLoginErrorResponse' + /v2/users/2fa-login: + post: + tags: [ authentication ] + summary: Second factor authentication. + operationId: PostUsers2FALogin + description: | + When user has 2FA enabled, this is the second call to perform after `/v2/users/login` call. + + Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs. + + The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`. + + Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository. + parameters: + - name: body + in: body + description: Login details. + required: true + schema: + $ref: '#/definitions/Users2FALoginRequest' + responses: + 200: + description: Authentication successful + schema: + $ref: '#/definitions/PostUsersLoginSuccessResponse' + 401: + description: Authentication failed or second factor required + schema: + $ref: '#/definitions/PostUsers2FALoginErrorResponse' /v2/access-tokens: post: summary: Create a personal access token @@ -1228,6 +1353,55 @@ paths: 404: $ref: "#/responses/NotFound" + /v2/repositories/{namespace}/{repository}/: + parameters: + - name: namespace + in: path + required: true + description: Namespace of the repository. + type: string + - name: repository + in: path + required: true + description: Name of the repository. + 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 + parameters: + - name: body + in: body + schema: + $ref: "#/definitions/update_repository" + responses: + 200: + description: Success + schema: + $ref: '#/definitions/repository' + 403: + description: Forbidden - access to the resource is forbidden, you don't have needed permission to perform this action. + schema: + $ref: '#/definitions/ErrorDetail' + examples: + application/json: + detail: You do not have permission to perform this action. + 404: + description: Repository not found or unable to access the ressource + schema: + $ref: '#/definitions/ErrorDetail' + examples: + application/json: + detail: Object not found + responses: BadRequest: description: Bad Request