Skip to content

Commit 91dd9c6

Browse files
lucadrudalucadruda
authored
Merge pull request #5 from docker/feat/improve-desc-and-required
Feat/improve desc and required. Add accounts
2 parents 9df707c + 7cff4ba commit 91dd9c6

File tree

4 files changed

+269
-31
lines changed

4 files changed

+269
-31
lines changed

‎specs/accounts.json‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
{
2+
"openapi": "3.0.3",
3+
"info": {
4+
"title": "Accounts API",
5+
"version": "1.0.0",
6+
"contact": {
7+
"name": "Docker Hub",
8+
"url": "https://github.com/docker",
9+
"email": "[email protected]"
10+
}
11+
},
12+
"tags": [
13+
{
14+
"name": "accounts",
15+
"x-displayName": "Accounts",
16+
"description": "Endpoints for managing accounts"
17+
}
18+
],
19+
"paths": {
20+
"/v2/user/orgs": {
21+
"get": {
22+
"summary": "Get organizations/namespaces for a user",
23+
"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.",
24+
"operationId": "get-namespaces",
25+
"tags": ["accounts"],
26+
"parameters": [
27+
{
28+
"in": "query",
29+
"name": "page",
30+
"schema": {
31+
"type": "string"
32+
},
33+
"description": "Page number for pagination. Default is 1.",
34+
"required": false
35+
},
36+
{
37+
"in": "query",
38+
"name": "page_size",
39+
"schema": {
40+
"type": "string"
41+
},
42+
"description": "Number of items per page",
43+
"required": false
44+
}
45+
],
46+
"responses": {
47+
"200": {
48+
"$ref": "#/components/responses/user_orgs_paginated_response"
49+
},
50+
"400": {
51+
"$ref": "#/components/responses/bad_request"
52+
},
53+
"401": {
54+
"$ref": "#/components/responses/forbidden"
55+
},
56+
"403": {
57+
"$ref": "#/components/responses/unauthorized"
58+
},
59+
"404": {
60+
"$ref": "#/components/responses/not_found"
61+
},
62+
"500": {
63+
"$ref": "#/components/responses/internal_error"
64+
}
65+
}
66+
}
67+
}
68+
},
69+
"components": {
70+
"schemas": {
71+
"organization": {
72+
"type": "object",
73+
"properties": {
74+
"orgname": {
75+
"type": "string",
76+
"description": "The name of the organization."
77+
}
78+
}
79+
},
80+
"pagination_next": {
81+
"type": "string",
82+
"description": "The URL or link for the next page of items.",
83+
"example": "https://hub.docker.com/v2/some/resources/items?page=3&page_size=20"
84+
},
85+
"pagination_count": {
86+
"type": "number",
87+
"description": "The total number of items that match with the search.",
88+
"example": 120
89+
},
90+
"pagination_previous": {
91+
"type": "string",
92+
"description": "The URL or link for the previous page of items.",
93+
"example": "https://hub.docker.com/v2/some/resources/items?page=1&page_size=20"
94+
},
95+
"user_organization": {
96+
"allOf": [
97+
{
98+
"$ref": "#/components/schemas/organization"
99+
},
100+
{
101+
"type": "object",
102+
"properties": {
103+
"user_role": {
104+
"type": "string",
105+
"example": "Owner"
106+
},
107+
"user_groups": {
108+
"type": "array",
109+
"items": {
110+
"type": "string"
111+
},
112+
"example": ["org123"]
113+
},
114+
"org_groups_count": {
115+
"type": "number",
116+
"example": 1
117+
},
118+
"plan_name": {
119+
"type": "string",
120+
"example": "free-team"
121+
}
122+
}
123+
}
124+
]
125+
},
126+
"error": {
127+
"type": "object",
128+
"properties": {
129+
"errinfo": {
130+
"type": "object",
131+
"items": {
132+
"type": "string"
133+
}
134+
},
135+
"detail": {
136+
"type": "string"
137+
},
138+
"message": {
139+
"type": "string"
140+
}
141+
}
142+
}
143+
},
144+
"responses": {
145+
"user_orgs_paginated_response": {
146+
"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.",
147+
"content": {
148+
"application/json": {
149+
"schema": {
150+
"properties": {
151+
"count": {
152+
"$ref": "#/components/schemas/pagination_count"
153+
},
154+
"previous": {
155+
"$ref": "#/components/schemas/pagination_previous"
156+
},
157+
"next": {
158+
"$ref": "#/components/schemas/pagination_next"
159+
},
160+
"results": {
161+
"type": "array",
162+
"items": {
163+
"$ref": "#/components/schemas/user_organization"
164+
}
165+
}
166+
}
167+
}
168+
}
169+
}
170+
},
171+
"bad_request": {
172+
"description": "Bad Request",
173+
"content": {
174+
"application/json": {
175+
"schema": {
176+
"$ref": "#/components/schemas/error"
177+
}
178+
}
179+
}
180+
},
181+
"no_content": {
182+
"description": "No Content"
183+
},
184+
"unauthorized": {
185+
"description": "Unauthorized",
186+
"content": {
187+
"application/json": {
188+
"schema": {
189+
"$ref": "#/components/schemas/error"
190+
}
191+
}
192+
}
193+
},
194+
"forbidden": {
195+
"description": "Forbidden",
196+
"content": {
197+
"application/json": {
198+
"schema": {
199+
"$ref": "#/components/schemas/error"
200+
}
201+
}
202+
}
203+
},
204+
"not_found": {
205+
"description": "Not Found",
206+
"content": {
207+
"application/json": {
208+
"schema": {
209+
"$ref": "#/components/schemas/error"
210+
}
211+
}
212+
}
213+
},
214+
"internal_error": {
215+
"description": "Internal",
216+
"content": {
217+
"application/json": {
218+
"schema": {
219+
"$ref": "#/components/schemas/error"
220+
}
221+
}
222+
}
223+
}
224+
}
225+
}
226+
}

‎specs/repos.json‎

Lines changed: 12 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -29,21 +29,6 @@
2929
"name": "repositories-webhooks",
3030
"x-displayName": "Repository webhooks",
3131
"description": "Endpoints for managing repository webhooks\n"
32-
},
33-
{
34-
"name": "registry-settings",
35-
"x-displayName": "Registry settings",
36-
"description": "Endpoints for managing org and user registry settings\n"
37-
},
38-
{
39-
"name": "repositories-advanced-images",
40-
"x-displayName": "Advanced Image Management",
41-
"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"
42-
},
43-
{
44-
"name": "repositories-autobuilds",
45-
"x-displayName": "Repository auto-builds",
46-
"description": "Endpoints for managing repository auto-builds\n"
4732
}
4833
],
4934
"paths": {
@@ -55,7 +40,7 @@
5540
],
5641
"post": {
5742
"summary": "Creates a new repository",
58-
"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",
43+
"description": "Creates a new repository in the provided namespace.\n\n The repository can be public or private. PAT scope: `repo:admin`\n",
5944
"operationId": "create-repository",
6045
"tags": ["repositories"],
6146
"requestBody": {
@@ -78,8 +63,8 @@
7863
},
7964
"get": {
8065
"summary": "Lists repositories under namespace",
81-
"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",
82-
"operationId": "list-repositories",
66+
"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",
67+
"operationId": "list-repositories-by-namespace",
8368
"tags": ["repositories"],
8469
"parameters": [
8570
{
@@ -157,7 +142,7 @@
157142
],
158143
"get": {
159144
"summary": "Gets repository info",
160-
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/`\n",
145+
"description": "PAT scope: `repo:public_read`\n",
161146
"operationId": "get-repository-info",
162147
"tags": ["repositories"],
163148
"responses": {
@@ -170,7 +155,7 @@
170155
}
171156
},
172157
"head": {
173-
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/`\n",
158+
"description": "PAT scope: `repo:public_read`\n",
174159
"summary": "Check repository",
175160
"operationId": "check-repository",
176161
"tags": ["repositories"],
@@ -185,7 +170,7 @@
185170
},
186171
"patch": {
187172
"summary": "Updates repository info",
188-
"description": "PAT scope: `repo:admin`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/`\n\nUpdates a repository info\n",
173+
"description": "PAT scope: `repo:admin`\n",
189174
"operationId": "update-repository-info",
190175
"tags": ["repositories"],
191176
"requestBody": {
@@ -214,7 +199,7 @@
214199
}
215200
],
216201
"get": {
217-
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/dockerfile/`\n",
202+
"description": "PAT scope: `repo:public_read`\n",
218203
"summary": "Gets dockerfile for repository",
219204
"operationId": "get-repository-dockerfile",
220205
"tags": ["repositories"],
@@ -261,7 +246,7 @@
261246
}
262247
],
263248
"get": {
264-
"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",
249+
"description": "List all tags for a repository. If the repository is private, the call must be authenticated. PAT scope: `repo:public_read`\n",
265250
"summary": "List repository tags",
266251
"operationId": "list-repository-tags",
267252
"tags": ["repositories"],
@@ -292,7 +277,7 @@
292277
}
293278
},
294279
"head": {
295-
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/tags`\n",
280+
"description": "PAT scope: `repo:public_read`\n",
296281
"summary": "Check repository tags",
297282
"operationId": "check-repository-tags",
298283
"tags": ["repositories"],
@@ -322,7 +307,7 @@
322307
}
323308
],
324309
"get": {
325-
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/tags/{tag}`\n",
310+
"description": "PAT scope: `repo:public_read`\n",
326311
"summary": "Read repository tag",
327312
"operationId": "read-repository-tag",
328313
"tags": ["repositories"],
@@ -339,7 +324,7 @@
339324
}
340325
},
341326
"head": {
342-
"description": "PAT scope: `repo:public_read`\n\nLegacy endpoint: `/v2/repositories/{namespace}/{repository}/tags/{tag}`\n",
327+
"description": "PAT scope: `repo:public_read`\n",
343328
"summary": "Check repository tag",
344329
"operationId": "check-repository-tag",
345330
"tags": ["repositories"],
@@ -1905,7 +1890,7 @@
19051890
}
19061891
},
19071892
"list_repositories": {
1908-
"description": "",
1893+
"description": "a paginated list of repositories under the provided namespace. If authenticated, the response will include private repositories",
19091894
"content": {
19101895
"application/json": {
19111896
"schema": {

‎src/api.ts‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,13 +52,26 @@ export class API extends Resource {
5252
method: method.toLowerCase(),
5353
operation: op,
5454
});
55+
let description =
56+
op.description ||
57+
op.summary ||
58+
`${method.toUpperCase()} ${path} (${this.config.name})`;
59+
if (op.responses) {
60+
for (const [status, response] of Object.entries(op.responses)) {
61+
if ((response as OpenAPIV3.ResponseObject).description) {
62+
description += `\n\nWhen response status is ${status} it returns ${
63+
(response as OpenAPIV3.ResponseObject).description
64+
}.`;
65+
}
66+
}
67+
}
5568
this.tools.set(toolName, {
5669
name: toolName,
57-
description:
58-
op.summary ||
59-
op.description ||
60-
`${method.toUpperCase()} ${path} (${this.config.name})`,
70+
description,
6171
inputSchema: this.generateInputSchema(op, path),
72+
annotations: {
73+
title: op.summary,
74+
},
6275
});
6376
}
6477
}

0 commit comments

Comments
 (0)