From patchwork Tue Oct 30 11:18:59 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 990729 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 42kpsc17fpz9s7T for ; Tue, 30 Oct 2018 22:20:04 +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="Prkntddx"; 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 42kpsb0R3DzF0RC for ; Tue, 30 Oct 2018 22:20:03 +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="Prkntddx"; 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.13; helo=relay013.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="Prkntddx"; dkim-atps=neutral Received: from relay013.mxrelay.co (relay013.mxrelay.co [185.234.75.13]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 42kpsS6bZhzDqfS for ; Tue, 30 Oct 2018 22:19:56 +1100 (AEDT) Received: from filter002.mxroute.com (unknown [185.133.192.179]) by relay013.mxrelay.co (Postfix) with ESMTP id 9D66E42D95 for ; Tue, 30 Oct 2018 11:19:23 +0000 (UTC) Received: from one.mxroute.com (one.mxroute.com [195.201.59.211]) by filter002.mxroute.com (Postfix) with ESMTPS id 5B5E43F547 for ; Tue, 30 Oct 2018 11:19:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=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: In-Reply-To:References:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=tWrRrhUrHyN09yx59rlb+r+rpnJtSK4GPEhnQCN4VH0=; b=Prkntddx7QwpsGRH+rjFjnFioP xEuOboxgwjy6KdMOS8KKqIPzvlxMNQqScMoyCKHSJBS8nu1jd8/VU1AkZdkhV8XftUT37642eewTe VGfR027Mpax3/xLYdDShl6hYYkbABBvtgdjhbQY/oJMQJZkW0NTye8+MSQnvx82k8NOmvvHF+wHNS neh/UQ5fo+FWlZXeDBOlCTnlpdOmeddm18N5cMNkvQDwo6Gy1YFPS/82AZgcEONgtvMu2zN1ZQchC qCsMrzJp6xFQ8EMfqZyhEO+iWts1vToZoHMIAhuCOaQddNbpGcLy3VaQ+NdX3TiD9v9CcJEiWODXW /O3/1RGA==; From: Stephen Finucane To: patchwork@lists.ozlabs.org Subject: [PATCH 00/17] Add OpenAPI 3.0.0 REST API spec Date: Tue, 30 Oct 2018 11:18:59 +0000 Message-Id: <20181030111916.7342-1-stephen@that.guru> X-Mailer: git-send-email 2.17.2 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" Round 2. When we first added the REST API, attempts were made to document this using OpenAPI 2.0 (f.k.a. Swagger). These floundered owing to the tediousness of writing said spec from scratch. Thankfully, tools have emerged [1][2] that allow us to generate specs from the code. The spec introduced here is based on the combined output of these tools, with some additional tweaks to work around gaps in the generated output (the embedded serializers in particular caused a lot of fuss). The end result is something that we can use to validate the API, validate clients and generate documentation from. To that effect, there are a couple of patches at the beginning of the series that clean up issues identified by running the tool. These should merge (and be backported) regardless of the progress on the spec itself. [1] https://www.django-rest-framework.org/api-guide/schemas/ [2] https://github.com/axnsan12/drf-yasg/ Stephen Finucane (17): REST: Add additional documentation REST: Show 'web_url' in embedded series responses REST: Ensure patch exists for check creation REST: Ensure submission exists for comment listing docs: Start documenting API using OpenAPI docs: Document the '/users' resource docs: Document the '/people' resource docs: Document the '/projects' resource docs: Document the '/bundles' resource docs: Document the '/covers' resource docs: Document the '/patches' resource docs: Document the '/series' resource docs: Document the '/covers/{coverID}/comments' resource docs: Document the '/patch/{patchID}/comments' resource docs: Document the '/patches/{patchID}/checks' resource docs: Document the '/events' resource docs: Make API document versioned .gitignore | 1 + docs/api/schemas/generate_schema.py | 29 + docs/api/schemas/patchwork.j2 | 2207 +++++++++++++++++ patchwork/api/check.py | 16 +- patchwork/api/comment.py | 5 + patchwork/api/embedded.py | 3 +- patchwork/api/index.py | 1 + patchwork/api/patch.py | 10 +- patchwork/api/project.py | 11 +- patchwork/api/user.py | 11 +- patchwork/tests/api/test_check.py | 31 +- patchwork/tests/api/test_comment.py | 13 + .../notes/issue-224-8f1c4207aa273ac6.yaml | 5 + .../notes/issue-225-94215600c1b23f6e.yaml | 6 + .../notes/issue-226-27ea72266d3ee9ac.yaml | 7 + 15 files changed, 2349 insertions(+), 7 deletions(-) create mode 100644 docs/api/schemas/generate_schema.py create mode 100644 docs/api/schemas/patchwork.j2 create mode 100644 releasenotes/notes/issue-224-8f1c4207aa273ac6.yaml create mode 100644 releasenotes/notes/issue-225-94215600c1b23f6e.yaml create mode 100644 releasenotes/notes/issue-226-27ea72266d3ee9ac.yaml