From: Stephen Finucane Date: Wed, 16 Nov 2016 23:25:00 +0000 (+0000) Subject: docs: Update swagger definition X-Git-Tag: v2.0.0-rc1~114 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6431aff9466b01e145b7b7b0fabcdfe968abd4ae;p=thirdparty%2Fpatchwork.git docs: Update swagger definition 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 --- diff --git a/docs/api.yaml b/docs/api.yaml index 62cebeca..3e79f0b5 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: