[PATCH 13/13] docs: Update swagger definition
Stephen Finucane
stephen at that.guru
Thu Nov 17 12:39:16 AEDT 2016
This is still not complete, but it bears a lot closer resemblence to
reality now.
Signed-off-by: Stephen Finucane <stephen at that.guru>
Cc: Andy Doan <andy.doan at linaro.org>
---
docs/api.yaml | 186 +++++++++++++++++++++++++++++++++++++++-------------------
1 file changed, 125 insertions(+), 61 deletions(-)
diff --git a/docs/api.yaml b/docs/api.yaml
index 62cebec..49a324c 100644
--- a/docs/api.yaml
+++ b/docs/api.yaml
@@ -52,7 +52,7 @@ paths:
$ref: '#/definitions/Error'
/projects/{projectId}:
get:
- summary: Retrieve a project by its ID.
+ summary: Retrieve a project.
description: |
Returns information about a single project available on this patchwork
instance. The response includes the display name and other details
@@ -72,6 +72,28 @@ paths:
description: Unexpected error.
schema:
$ref: '#/definitions/Error'
+ patch:
+ summary: Update a project.
+ description: |
+ Update information about a single project available on this patchwork
+ instance.
+ parameters:
+ - $ref: '#/parameters/projectId'
+ tags:
+ - Projects
+ responses:
+ 200:
+ description: A project object.
+ schema:
+ $ref: '#/definitions/Project'
+ 403:
+ description: The user is not authenticated or is not a superuser.
+ 404:
+ description: The project does not exist.
+ default:
+ description: Unexpected error.
+ schema:
+ $ref: '#/definitions/Error'
/people:
get:
summary: List available people.
@@ -91,13 +113,15 @@ paths:
type: array
items:
$ref: '#/definitions/People'
+ 403:
+ description: The user is not authenticated.
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Error'
/people/{personId}:
get:
- summary: Retrieve a person by its ID.
+ summary: Retrieve a person.
description: |
Returns information about a single person who has submitted patches on
this patchwork instance. The response includes the name, email and
@@ -111,8 +135,10 @@ paths:
description: A person object.
schema:
$ref: '#/definitions/People'
+ 403:
+ description: The user is not authenticated.
404:
- description: The project does not exist
+ description: The person does not exist.
default:
description: Unexpected error.
schema:
@@ -131,22 +157,6 @@ paths:
- $ref: '#/parameters/pageParam'
- $ref: '#/parameters/sinceParam'
- $ref: '#/parameters/untilParam'
- - name: project
- description: project name by which to filter
- in: query
- type: string
- - name: state
- description: patch state by which to filter
- in: query
- type: string
- - name: submitter
- description: username or email of submitter by which to filter
- in: query
- type: string
- - name: delegate
- description: username or email of delegate by which to filter
- in: query
- type: string
responses:
200:
description: An array of patch objects.
@@ -160,7 +170,7 @@ paths:
$ref: '#/definitions/Error'
/patches/{patchId}:
get:
- summary: Retrieve a patch by its ID.
+ summary: Retrieve a patch.
description: |
Returns information about a single patch available on this patchwork
instance. The response includes the name, diff and other details
@@ -180,41 +190,41 @@ paths:
description: Unexpected error.
schema:
$ref: '#/definitions/Error'
- /patches/{patchId}/checks:
- get:
- summary: List check statuses for given patch.
+ patch:
+ summary: Update a patch.
description: |
- Checks store the results of any tests executed (or executing) for a
- given patch. This is useful, for example, when using a continuous
- integration (CI) system to test patches.
+ Update information about a patch.
parameters:
- $ref: '#/parameters/patchId'
- - $ref: '#/parameters/perPageParam'
- - $ref: '#/parameters/pageParam'
tags:
- - Checks
+ - Patches
responses:
200:
- description: An array of check objects.
+ description: A patch object.
schema:
- type: array
- items:
- $ref: '#/definitions/Check'
+ $ref: '#/definitions/PatchDetail'
+ 403:
+ description: |
+ The user is not authenticated, or the user did not create the
+ patch and is not a super user.
404:
description: The patch does not exist
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Error'
- /patches/{patchId}/check:
+ - $ref: '#/parameters/patchId'
+ /patches/{patchId}/checks:
get:
- summary: Retrieve combined check status for given patch.
+ summary: List checks for given patch.
description: |
Checks store the results of any tests executed (or executing) for a
given patch. This is useful, for example, when using a continuous
integration (CI) system to test patches.
parameters:
- $ref: '#/parameters/patchId'
+ - $ref: '#/parameters/perPageParam'
+ - $ref: '#/parameters/pageParam'
tags:
- Checks
responses:
@@ -223,11 +233,12 @@ paths:
schema:
$ref: '#/definitions/Check'
404:
- description: The patch does not exist
+ description: The parent patch does not exist
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Error'
+ # TODO(stephenfin): Document creation of checks, listing of users
parameters:
# ID Parameters
projectId:
@@ -293,18 +304,21 @@ definitions:
id:
type: integer
description: Unique identifier of project.
+ url:
+ type: string
+ description: url to project.
name:
type: string
description: Name of project.
link_name:
type: string
description: Link name of project.
- list_email:
- type: string
- description: Mailing list email address for project.
list_id:
type: string
description: Mailing list identifier for project.
+ list_email:
+ type: string
+ description: Mailing list email address for project.
web_url:
type: string
description: Upstream website URL for project.
@@ -319,33 +333,46 @@ definitions:
id:
type: integer
description: Unique identifier of patch.
- project_url:
- type: integer
- description: Project ID of patch.
- name:
+ url:
type: string
- description: Name of patch.
+ description: URL to patch.
+ project:
+ type: string
+ description: URL to patch's project.
+ msgid:
+ type: string
+ description: Message ID header from patch mail.
date:
type: string
format: date-time
description: Submission date of patch.
+ name:
+ type: string
+ description: Name of patch.
+ commit_ref:
+ type: string
+ description: Ref of committed patch.
+ pull_url:
+ type: string
+ description: URL to patch pull request.
+ state:
+ type: string
+ description: The state of the patch.
+ archived:
+ type: boolean
+ description: Archival state of patch.
+ hash:
+ type: string
+ description: Hash of patch's diff.
submitter:
type: string
description: URL for submitter of patch.
delegate:
type: integer
description: URL for delegate assigned to patch.
- state:
- type: string
- description: The state of the patch.
- mbox_url:
+ mbox:
type: string
description: Link to the raw patch mbox contents.
- tags:
- type: array
- description: Tags associated with patch.
- items:
- type: string
check:
type: string
description: The combined check status for the patch.
@@ -354,6 +381,14 @@ definitions:
- success
- warning
- fail
+ checks:
+ type: string
+ description: URL to patch's checks endpoint.
+ tags:
+ type: array
+ description: Tags associated with patch.
+ items:
+ type: string
PatchDetail:
allOf:
$ref: '#/definitions/Patch'
@@ -374,23 +409,32 @@ definitions:
id:
type: integer
description: Unique identifier of person.
+ url:
+ type: string
+ description: URL to person.
name:
type: string
description: Name of person.
email:
type: string
description: Email of person.
- user_url:
+ user:
type: string
- description: URL for Patchwork user account connected to person.
+ description: URL for user connected to person.
Check:
properties:
id:
type: integer
description: Unique identifier of check.
- user_url:
+ url:
+ type: string
+ description: URL to check.
+ user:
type: string
description: URL for creator of check.
+ date:
+ type: string
+ format: date-time
state:
type: string
description: The state of the check.
@@ -399,17 +443,37 @@ definitions:
- success
- warning
- fail
- url:
+ target_url:
type: string
description: The target URL associated with this check.
- description:
- type: string
- description: A brief description of the check.
context:
type: string
description: |
A label to discern check from checks of other testing systems.
- Error:
+ description:
+ type: string
+ description: A brief description of the check.
+ User:
+ properties:
+ id:
+ type: integer
+ description: Unique identifier of user.
+ url:
+ type: string
+ description: URL to user.
+ username:
+ type: string
+ description: Username of user.
+ first_name:
+ type: string
+ description: First name of user.
+ last_name:
+ type: string
+ description: Last name of user.
+ email:
+ type: string
+ description: Email of user.
+ Error:
properties:
code:
type: integer
--
2.7.4
More information about the Patchwork
mailing list