From patchwork Tue Oct 30 11:19:05 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 990733 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [203.11.71.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 42kpwZ3Q75z9s7W for ; Tue, 30 Oct 2018 22:22:38 +1100 (AEDT) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=that.guru Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="gDKAhp7u"; dkim-atps=neutral Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 42kpwZ1RmlzDqfH for ; Tue, 30 Oct 2018 22:22:38 +1100 (AEDT) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=that.guru Authentication-Results: lists.ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="gDKAhp7u"; dkim-atps=neutral X-Original-To: patchwork@lists.ozlabs.org Delivered-To: patchwork@lists.ozlabs.org Authentication-Results: lists.ozlabs.org; spf=none (mailfrom) smtp.mailfrom=that.guru (client-ip=185.234.75.18; helo=relay018.mxrelay.co; envelope-from=stephen@that.guru; receiver=) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=that.guru Authentication-Results: lists.ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="gDKAhp7u"; dkim-atps=neutral Received: from relay018.mxrelay.co (relay018.mxrelay.co [185.234.75.18]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 42kpsW75BszDqfS for ; Tue, 30 Oct 2018 22:19:59 +1100 (AEDT) Received: from filter002.mxroute.com (unknown [185.133.192.179]) by relay018.mxrelay.co (Postfix) with ESMTP id 71BE14056F for ; Tue, 30 Oct 2018 11:19:27 +0000 (UTC) Received: from one.mxroute.com (one.mxroute.com [195.201.59.211]) by filter002.mxroute.com (Postfix) with ESMTPS id 4EEB73F3DB for ; Tue, 30 Oct 2018 11:19:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=33MCpOorRkdfOxwofR+/bNJpcJyfXa4mWZooEIrDDXw=; b=gDKAhp7u6I3QOtAIZnKdWx13VO 80u8MS9jbGsPCwqTrHutbW+jv0Fe3nw4eyDock2uHH8NmosaCIrMTHnSQwDaOdF3mpI0fb4bJ59Ts BfTor7QRC354M6lexXdHB7Qr9Mr3O2YtuN6/7GRcRUHW6WW27gxr0k710q68Rnb0EsgpSb491oydy FiWvYxQBSyCkbZ4z2xRwFsCFnCuDZcpqIE4o2HLbfkOUvJwXCx0H9HEBBwHQf7OTnFlUun28WbC0s MlowIbaKTpvczkMG0o1geyPJBOoLJ1TV8IOGkPwTW2YqbKTUf9eciGtQsUNkCp9eivgkQ+DzluvNx h9d92qkg==; From: Stephen Finucane To: patchwork@lists.ozlabs.org Subject: [PATCH 06/17] docs: Document the '/users' resource Date: Tue, 30 Oct 2018 11:19:05 +0000 Message-Id: <20181030111916.7342-7-stephen@that.guru> X-Mailer: git-send-email 2.17.2 In-Reply-To: <20181030111916.7342-1-stephen@that.guru> References: <20181030111916.7342-1-stephen@that.guru> X-AuthUser: stephen@that.guru X-BeenThere: patchwork@lists.ozlabs.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Patchwork development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: patchwork-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Patchwork" This introduces our first use of parameters, both in the path and the query. The latter are extracted out as they'll be used by later changes. Signed-off-by: Stephen Finucane --- docs/api/schemas/patchwork.yaml | 232 ++++++++++++++++++++++++++++++++ 1 file changed, 232 insertions(+) diff --git a/docs/api/schemas/patchwork.yaml b/docs/api/schemas/patchwork.yaml index 804d0c3f..eabdc55d 100644 --- a/docs/api/schemas/patchwork.yaml +++ b/docs/api/schemas/patchwork.yaml @@ -25,6 +25,150 @@ paths: $ref: '#/components/schemas/Index' tags: - api + /api/users/: + get: + description: List users. + operationId: users_list + parameters: + - $ref: '#/components/parameters/Page' + - $ref: '#/components/parameters/PageSize' + - $ref: '#/components/parameters/Order' + - $ref: '#/components/parameters/Search' + responses: + '200': + description: '' + headers: + Link: + $ref: '#/components/headers/Link' + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/User' + '403': + description: 'Forbidden' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - users + /api/users/{id}/: + get: + description: Show a user. + operationId: users_read + parameters: + - in: path + name: id + required: true + schema: + description: A unique integer value identifying this user. + title: ID + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/User' + '400': + description: 'Bad request' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorUserUpdate' + '403': + description: 'Forbidden' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: 'Not found' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - users + patch: + description: Update a user (partial). + operationId: users_partial_update + parameters: + - in: path + name: id + required: true + schema: + description: A unique integer value identifying this user. + title: ID + type: integer + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/User' + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/User' + '403': + description: 'Forbidden' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: 'Not found' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - users + put: + description: Update a user. + operationId: users_update + parameters: + - in: path + name: id + required: true + schema: + description: A unique integer value identifying this user. + title: ID + type: integer + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/User' + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/User' + '403': + description: 'Forbidden' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: 'Not found' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - users components: securitySchemes: basicAuth: @@ -33,6 +177,44 @@ components: apiKeyAuth: type: http scheme: bearer + parameters: + Page: + in: query + name: page + schema: + description: A page number within the paginated result set. + title: Page + type: integer + PageSize: + in: query + name: per_page + schema: + description: Number of results to return per page. + title: Page size + type: integer + Order: + in: query + name: order + schema: + description: Which field to use when ordering the results. + title: Ordering + type: string + Search: + in: query + name: q + schema: + description: A search term. + title: Search + type: string + headers: + Link: + description: | + Links to related resources, in the format defined by + [RFC 5988](https://tools.ietf.org/html/rfc5988#section-5). + This will include a link with relation type `next` to the + next page, if there is a next page. + schema: + type: string schemas: Index: type: object @@ -72,5 +254,55 @@ components: type: string format: uri readOnly: true + User: + type: object + properties: + id: + title: ID + type: integer + readOnly: true + url: + title: Url + type: string + format: uri + readOnly: true + username: + title: Username + type: string + readOnly: true + minLength: 1 + maxLength: 150 + first_name: + title: First name + type: string + maxLength: 30 + last_name: + title: Last name + type: string + maxLength: 150 + email: + title: Email address + type: string + format: email + readOnly: true + minLength: 1 + Error: + type: object + properties: + detail: + title: Detail + type: string + readOnly: true + ErrorUserUpdate: + type: object + properties: + first_name: + title: First name + type: string + readOnly: true + last_name: + title: First name + type: string + readOnly: true servers: - url: 'https://patchwork.ozlabs.org/api/1.1'