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 <yves.brissaud@docker.com>

* rename repository tag to repositories

Signed-off-by: Yves Brissaud <yves.brissaud@docker.com>

* improve the examples and 404 on edit repo

Signed-off-by: Yves Brissaud <yves.brissaud@docker.com>
This commit is contained in:
Yves Brissaud 2022-03-09 17:21:48 +01:00 committed by GitHub
parent 22fe2b449b
commit 117dfca0fc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 177 additions and 3 deletions

View File

@ -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