[PATCH v2 13/13] docs: Update swagger definition

Stephen Finucane stephen at that.guru
Sun Nov 20 03:51:28 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