[PATCH v3 16/16] docs: Update swagger definition
Stephen Finucane
stephen at that.guru
Sat Nov 26 05:18:35 AEDT 2016
There are a couple of changes needed:
- Add the '/users' endpoint
- Add PATCH support for the '/projects' endpoint
- Add information on authentication
- Clean up some documentation
- Remove some non-implemented parameters
This is still not complete, but it bears a lot closer resemblence to
reality now.
Signed-off-by: Stephen Finucane <stephen at that.guru>
---
docs/api.yaml | 298 +++++++++++++++++++++++++++++++++++++++++-----------------
1 file changed, 210 insertions(+), 88 deletions(-)
diff --git a/docs/api.yaml b/docs/api.yaml
index 62cebec..3e79f0b 100644
--- a/docs/api.yaml
+++ b/docs/api.yaml
@@ -7,7 +7,12 @@ info:
version: "1.0"
host: patchwork.ozlabs.org
schemes:
+ - http
- https
+securityDefinitions:
+ basicAuth:
+ type: basic
+ description: HTTP Basic Authentication. Works over `HTTP` and `HTTPS`
basePath: /api/1.0
produces:
- application/json
@@ -32,8 +37,7 @@ paths:
summary: List available projects.
description: |
Returns information about all projects available on this patchwork
- instance. The response includes the display name and other details
- about each project.
+ instance.
parameters:
- $ref: '#/parameters/perPageParam'
- $ref: '#/parameters/pageParam'
@@ -52,11 +56,10 @@ 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
- about each project.
+ instance.
parameters:
- $ref: '#/parameters/projectId'
tags:
@@ -72,18 +75,41 @@ 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
+ security:
+ - basicAuth: []
+ 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.
description: |
Returns information about all people who have submitted patches on this
- patchwork instance. The response includes the name, email and other
- details about each person.
- tags:
- - People
+ patchwork instance.
parameters:
- $ref: '#/parameters/perPageParam'
- $ref: '#/parameters/pageParam'
+ tags:
+ - People
responses:
200:
description: An array of people objects.
@@ -91,17 +117,18 @@ 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
- other details about each person.
+ this patchwork instance.
parameters:
- $ref: '#/parameters/personId'
tags:
@@ -111,42 +138,76 @@ 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:
+ $ref: '#/definitions/Error'
+ /users:
+ get:
+ summary: List available users.
+ description: |
+ Returns information about all users registerd on this Patchwork
+ instance.
+ parameters:
+ - $ref: '#/parameters/perPageParam'
+ - $ref: '#/parameters/pageParam'
+ tags:
+ - Users
+ security:
+ - basicAuth: []
+ responses:
+ 200:
+ description: An array of user objects.
+ schema:
+ type: array
+ items:
+ $ref: '#/definitions/User'
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Error'
+ /users/{userId}:
+ get:
+ summary: Retrieve a user.
+ description: |
+ Returns information about a single user registerd on this Patchwork
+ instance.
+ parameters:
+ - $ref: '#/parameters/userId'
+ tags:
+ - Users
+ security:
+ - basicAuth: []
+ responses:
+ 200:
+ description: A user object.
+ schema:
+ $ref: '#/definitions/User'
+ 403:
+ description: The user is not authenticated.
+ 404:
+ description: The user does not exists.
+ default:
+ description: Unexpected error.
+ schema:
+ $ref: '#/definitions/User'
/patches:
get:
summary: List available patches
description: |
Returns information about all patches available on this patchwork
- instance. The response includes the name, diff and other details
- about each patch.
- tags:
- - Patches
+ instance.
parameters:
- $ref: '#/parameters/perPageParam'
- $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
+ tags:
+ - Patches
responses:
200:
description: An array of patch objects.
@@ -160,11 +221,10 @@ 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
- about each patch.
+ instance.
parameters:
- $ref: '#/parameters/patchId'
tags:
@@ -180,41 +240,42 @@ 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
+ security:
+ - basicAuth: []
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:
+ /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 +284,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:
@@ -244,6 +306,13 @@ parameters:
type: integer
format: int32
required: true
+ userId:
+ name: userId
+ description: ID of a user.
+ in: path
+ type: integer
+ format: int32
+ required: true
patchId:
name: patchId
description: |
@@ -293,18 +362,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 +391,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,43 +439,60 @@ 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'
- properties:
- diff:
- type: string
- description: Diff of patch.
- content:
+ - $ref: '#/definitions/Patch'
+ properties:
+ diff:
+ type: string
+ description: Diff of patch.
+ content:
+ type: string
+ description: Message of patch.
+ headers:
+ type: array
+ description: The headers of the patch.
+ items:
type: string
- description: Message of patch.
- headers:
- type: array
- description: The headers of the patch.
- items:
- type: string
People:
properties:
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,16 +501,36 @@ 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.
+ 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:
--
2.7.4
More information about the Patchwork
mailing list