Skip to content

Feat/improve desc and required. Add accounts #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 18, 2025
Merged

Feat/improve desc and required. Add accounts #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
778f9da
add accounts
lucadruda Jun 18, 2025
3a82332
add account spec
lucadruda Jun 18, 2025
7cff4ba
fix specs
lucadruda Jun 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
226 changes: 226 additions & 0 deletions specs/accounts.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,226 @@
{
"openapi": "3.0.3",
"info": {
"title": "Accounts API",
"version": "1.0.0",
"contact": {
"name": "Docker Hub",
"url": "https://github.com/docker",
"email": "[email protected]"
}
},
"tags": [
{
"name": "accounts",
"x-displayName": "Accounts",
"description": "Endpoints for managing accounts"
}
],
"paths": {
"/v2/user/orgs": {
"get": {
"summary": "Get organizations/namespaces for a user",
"description": "Returns a list of namespaces the user is a member of including namespaces of organizations he is an owner or an editor of. Retrieves the list of organization namespaces the user has access to. Note: This does not include the user's personal namespace, which is named after the user's username.",
"operationId": "get-namespaces",
"tags": ["accounts"],
"parameters": [
{
"in": "query",
"name": "page",
"schema": {
"type": "string"
},
"description": "Page number for pagination. Default is 1.",
"required": false
},
{
"in": "query",
"name": "page_size",
"schema": {
"type": "string"
},
"description": "Number of items per page",
"required": false
}
],
"responses": {
"200": {
"$ref": "#/components/responses/user_orgs_paginated_response"
},
"400": {
"$ref": "#/components/responses/bad_request"
},
"401": {
"$ref": "#/components/responses/forbidden"
},
"403": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not_found"
},
"500": {
"$ref": "#/components/responses/internal_error"
}
}
}
}
},
"components": {
"schemas": {
"organization": {
"type": "object",
"properties": {
"orgname": {
"type": "string",
"description": "The name of the organization."
}
}
},
"pagination_next": {
"type": "string",
"description": "The URL or link for the next page of items.",
"example": "https://hub.docker.com/v2/some/resources/items?page=3&page_size=20"
},
"pagination_count": {
"type": "number",
"description": "The total number of items that match with the search.",
"example": 120
},
"pagination_previous": {
"type": "string",
"description": "The URL or link for the previous page of items.",
"example": "https://hub.docker.com/v2/some/resources/items?page=1&page_size=20"
},
"user_organization": {
"allOf": [
{
"$ref": "#/components/schemas/organization"
},
{
"type": "object",
"properties": {
"user_role": {
"type": "string",
"example": "Owner"
},
"user_groups": {
"type": "array",
"items": {
"type": "string"
},
"example": ["org123"]
},
"org_groups_count": {
"type": "number",
"example": 1
},
"plan_name": {
"type": "string",
"example": "free-team"
}
}
}
]
},
"error": {
"type": "object",
"properties": {
"errinfo": {
"type": "object",
"items": {
"type": "string"
}
},
"detail": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"responses": {
"user_orgs_paginated_response": {
"description": "A list of the user's organizations/namespaces. Note: The personal namespace of the authenticated user is not included in the list of namespaces (organizations) returned by this endpoint and must be queried separately. If this endpoint is called in the context of listing all repositories user have access to, then an extra invocation of the `list-repositories-by-namespace` endpoint should be done to get repositories under the personal namespace of the user.",
"content": {
"application/json": {
"schema": {
"properties": {
"count": {
"$ref": "#/components/schemas/pagination_count"
},
"previous": {
"$ref": "#/components/schemas/pagination_previous"
},
"next": {
"$ref": "#/components/schemas/pagination_next"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/user_organization"
}
}
}
}
}
}
},
"bad_request": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
},
"no_content": {
"description": "No Content"
},
"unauthorized": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
},
"forbidden": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
},
"not_found": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
},
"internal_error": {
"description": "Internal",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
}
}
}
}
39 changes: 12 additions & 27 deletions specs/repos.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,21 +29,6 @@
"name": "repositories-webhooks",
"x-displayName": "Repository webhooks",
"description": "Endpoints for managing repository webhooks\n"
},
{
"name": "registry-settings",
"x-displayName": "Registry settings",
"description": "Endpoints for managing org and user registry settings\n"
},
{
"name": "repositories-advanced-images",
"x-displayName": "Advanced Image Management",
"description": "The Advanced Image Management API endpoints allow you to manage Docker\nimages across all repositories.\n\nFor more information, see [Advanced Image Management dashboard](/docker-hub/image-management/).\n"
},
{
"name": "repositories-autobuilds",
"x-displayName": "Repository auto-builds",
"description": "Endpoints for managing repository auto-builds\n"
}
],
"paths": {
Expand All @@ -55,7 +40,7 @@
],
"post": {
"summary": "Creates a new repository",
"description": "Creates a new repository in the provided namespace.\n\n The repository can be public or private. PAT scope: `repo:admin`\n\nLegacy endpoint: `/v2/repositories/`\n",
"description": "Creates a new repository in the provided namespace.\n\n The repository can be public or private. PAT scope: `repo:admin`\n",
"operationId": "create-repository",
"tags": ["repositories"],
"requestBody": {
Expand All @@ -78,8 +63,8 @@
},
"get": {
"summary": "Lists repositories under namespace",
"description": "List all repositories under the provided namespace. If authenticated, the response will include private repositories.\n\nPAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/`\n",
"operationId": "list-repositories",
"description": "List all repositories under the provided namespace. If authenticated, the response will include private repositories. Namespace is a mandatory parameter. To list repositories under the `personal` namespace, the user must explicitly provide the exact username as the namespace parameter.\n\nPAT scope: `repo:public_read`.\n",
"operationId": "list-repositories-by-namespace",
"tags": ["repositories"],
"parameters": [
{
Expand Down Expand Up @@ -157,7 +142,7 @@
],
"get": {
"summary": "Gets repository info",
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/`\n",
"description": "PAT scope: `repo:public_read`\n",
"operationId": "get-repository-info",
"tags": ["repositories"],
"responses": {
Expand All @@ -170,7 +155,7 @@
}
},
"head": {
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/`\n",
"description": "PAT scope: `repo:public_read`\n",
"summary": "Check repository",
"operationId": "check-repository",
"tags": ["repositories"],
Expand All @@ -185,7 +170,7 @@
},
"patch": {
"summary": "Updates repository info",
"description": "PAT scope: `repo:admin`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/`\n\nUpdates a repository info\n",
"description": "PAT scope: `repo:admin`\n",
"operationId": "update-repository-info",
"tags": ["repositories"],
"requestBody": {
Expand Down Expand Up @@ -214,7 +199,7 @@
}
],
"get": {
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/dockerfile/`\n",
"description": "PAT scope: `repo:public_read`\n",
"summary": "Gets dockerfile for repository",
"operationId": "get-repository-dockerfile",
"tags": ["repositories"],
Expand Down Expand Up @@ -261,7 +246,7 @@
}
],
"get": {
"description": "List all tags for a repository. If the repository is private, the call must be authenticated. PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/tags`\n",
"description": "List all tags for a repository. If the repository is private, the call must be authenticated. PAT scope: `repo:public_read`\n",
"summary": "List repository tags",
"operationId": "list-repository-tags",
"tags": ["repositories"],
Expand Down Expand Up @@ -292,7 +277,7 @@
}
},
"head": {
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/tags`\n",
"description": "PAT scope: `repo:public_read`\n",
"summary": "Check repository tags",
"operationId": "check-repository-tags",
"tags": ["repositories"],
Expand Down Expand Up @@ -322,7 +307,7 @@
}
],
"get": {
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/tags/{tag}`\n",
"description": "PAT scope: `repo:public_read`\n",
"summary": "Read repository tag",
"operationId": "read-repository-tag",
"tags": ["repositories"],
Expand All @@ -339,7 +324,7 @@
}
},
"head": {
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/tags/{tag}`\n",
"description": "PAT scope: `repo:public_read`\n",
"summary": "Check repository tag",
"operationId": "check-repository-tag",
"tags": ["repositories"],
Expand Down Expand Up @@ -1905,7 +1890,7 @@
}
},
"list_repositories": {
"description": "",
"description": "a paginated list of repositories under the provided namespace. If authenticated, the response will include private repositories",
"content": {
"application/json": {
"schema": {
Expand Down
21 changes: 17 additions & 4 deletions src/api.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,26 @@ export class API extends Resource {
method: method.toLowerCase(),
operation: op,
});
let description =
op.description ||
op.summary ||
`${method.toUpperCase()} ${path} (${this.config.name})`;
if (op.responses) {
for (const [status, response] of Object.entries(op.responses)) {
if ((response as OpenAPIV3.ResponseObject).description) {
description += `\n\nWhen response status is ${status} it returns ${
(response as OpenAPIV3.ResponseObject).description
}.`;
}
}
}
this.tools.set(toolName, {
name: toolName,
description:
op.summary ||
op.description ||
`${method.toUpperCase()} ${path} (${this.config.name})`,
description,
inputSchema: this.generateInputSchema(op, path),
annotations: {
title: op.summary,
},
});
}
}
Expand Down
Loading
Loading