From patchwork Tue Oct 30 11:19:16 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 990741 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 42kq1H2XGQz9s7W for ; Tue, 30 Oct 2018 22:26:43 +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="CeYyx75r"; 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 42kq1H0yjTzDrPc for ; Tue, 30 Oct 2018 22:26:43 +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="CeYyx75r"; 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.17; helo=relay017.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="CeYyx75r"; dkim-atps=neutral Received: from relay017.mxrelay.co (relay017.mxrelay.co [185.234.75.17]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 42kpsc6hG3zF0RC for ; Tue, 30 Oct 2018 22:20:04 +1100 (AEDT) Received: from filter002.mxroute.com (unknown [185.133.192.179]) by relay017.mxrelay.co (Postfix) with ESMTP id 5A9B742C62 for ; Tue, 30 Oct 2018 11:19:32 +0000 (UTC) Received: from one.mxroute.com (one.mxroute.com [195.201.59.211]) by filter002.mxroute.com (Postfix) with ESMTPS id 3F4DE3F546 for ; Tue, 30 Oct 2018 11:19:32 +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=X1rNYXJCKpvDt9XRZ7fvyQCkeyqdfuWaMHECveN2Dqw=; b=CeYyx75rquXQZfh17Uiva8bX2e 245A4oNBfyAuTw8CY6J9d5g5L2HoFYTi5W9t5T4CFoX+cbcTvK8Ql2Z7RVTaUL5HygeFZ6tlx7dD5 uOsqhV2IHiJvnzUXQGNeMkpHI9YdQo+CA3INTca8gaIZZ0xcdDi8AsarywQXnr37MJnO9iD1f67es ZEEOcTZiojwLjgVTreXAFGKtlis+32H78rMwa0bNJn5+RZy+oe1kM6hKEDY8Dw+mDYvk0ZEEKRAvB YNBsWZKqxpDsREbB6X1zZ22egIVI0uB+H5nOetrNuNcxKqCQSkUTBk7Li6lnjRf5wADb0XBXOt3+D k+yWtVXw==; From: Stephen Finucane To: patchwork@lists.ozlabs.org Subject: [PATCH 17/17] docs: Make API document versioned Date: Tue, 30 Oct 2018 11:19:16 +0000 Message-Id: <20181030111916.7342-18-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" OpenAPI doesn't appear to support versioning natively, suggesting instead that separate documents are kept. Rather than doing this manually, let's use a templating tool - Jinja2, in this case - to generate these document for us from a single master document. Signed-off-by: Stephen Finucane --- .gitignore | 1 + docs/api/schemas/generate_schema.py | 29 +++++++++++++++++ .../schemas/{patchwork.yaml => patchwork.j2} | 31 +++++++++++++++++-- 3 files changed, 59 insertions(+), 2 deletions(-) create mode 100644 docs/api/schemas/generate_schema.py rename docs/api/schemas/{patchwork.yaml => patchwork.j2} (98%) diff --git a/.gitignore b/.gitignore index a33d1029..da53b382 100644 --- a/.gitignore +++ b/.gitignore @@ -44,6 +44,7 @@ htmlcov/ # Sphinx stuff /docs/_build +/docs/api/schemas/v* # Selenium test artifacts /selenium.log diff --git a/docs/api/schemas/generate_schema.py b/docs/api/schemas/generate_schema.py new file mode 100644 index 00000000..65d4ed82 --- /dev/null +++ b/docs/api/schemas/generate_schema.py @@ -0,0 +1,29 @@ +#!/usr/bin/env python3 + +import os + +import jinja2 + +ROOT_DIR = os.path.dirname(os.path.realpath(__file__)) +VERSIONS = [(1, 0), (1, 1)] + + +def generate_schema(): + env = jinja2.Environment( + loader=jinja2.FileSystemLoader(ROOT_DIR), + trim_blocks=True, + lstrip_blocks=True) + template = env.get_template('patchwork.j2') + + for version in VERSIONS: + version_dir = os.path.join(ROOT_DIR, 'v%d.%d' % version) + + if not os.path.exists(version_dir): + os.mkdir(version_dir) + + with open(os.path.join(version_dir, 'patchwork.yaml'), 'wb') as fh: + template.stream(version=version).dump(fh, encoding='utf-8') + + +if __name__ == '__main__': + generate_schema() diff --git a/docs/api/schemas/patchwork.yaml b/docs/api/schemas/patchwork.j2 similarity index 98% rename from docs/api/schemas/patchwork.yaml rename to docs/api/schemas/patchwork.j2 index cf78a87f..752a9c5e 100644 --- a/docs/api/schemas/patchwork.yaml +++ b/docs/api/schemas/patchwork.j2 @@ -1,3 +1,6 @@ +{# You can obviously ignore the below when editing this template #} +# DO NOT EDIT THIS FILE. It is generated from a template. Changes should be +# proposed against the template. openapi: '3.0.0' info: title: Patchwork API @@ -9,7 +12,7 @@ info: license: name: GPL v2 License url: https://www.gnu.org/licenses/gpl-2.0.html - version: '1.1' + version: '{{ "%d.%d"|format(*version) }}' paths: /api/: get: @@ -1137,11 +1140,13 @@ components: type: string format: uri readOnly: true +{% if version == '1.0' %} web_url: title: Web url type: string format: uri readOnly: true +{% endif %} project: $ref: '#/components/schemas/ProjectEmbedded' name: @@ -1256,11 +1261,13 @@ components: title: ID type: integer readOnly: true +{% if version > (1, 0) %} web_url: title: Web url type: string format: uri readOnly: true +{% endif %} msgid: title: Msgid type: string @@ -1302,11 +1309,13 @@ components: type: string format: uri readOnly: true +{% if version > (1, 0) %} web_url: title: Web url type: string format: uri readOnly: true +{% endif %} project: $ref: '#/components/schemas/ProjectEmbedded' msgid: @@ -1326,18 +1335,22 @@ components: minLength: 1 submitter: $ref: '#/components/schemas/PersonEmbedded' +{% if version > (1, 0) %} mbox: title: Mbox type: string format: uri readOnly: true +{% endif %} series: $ref: '#/components/schemas/SeriesEmbedded' +{% if version > (1, 0) %} comments: title: Comments type: string format: uri readOnly: true +{% endif %} CoverLetterDetail: allOf: - $ref: '#/components/schemas/CoverLetterList' @@ -1506,11 +1519,13 @@ components: type: string format: uri readOnly: true +{% if version > (1, 0) %} web_url: title: Web url type: string format: uri readOnly: true +{% endif %} project: $ref: '#/components/schemas/ProjectEmbedded' msgid: @@ -1566,11 +1581,13 @@ components: readOnly: true series: $ref: '#/components/schemas/SeriesEmbedded' +{% if version > (1, 0) %} comments: title: Comments type: string format: uri readOnly: true +{% endif %} check: title: Check type: string @@ -1725,6 +1742,7 @@ components: $ref: '#/components/schemas/UserEmbedded' readOnly: true uniqueItems: true +{% if version > (1, 0) %} subject_match: title: Subject match description: Regex to match the subject against if only part of emails @@ -1735,6 +1753,7 @@ components: type: string readOnly: true minLength: 1 +{% endif %} Series: type: object properties: @@ -1747,11 +1766,13 @@ components: type: string format: uri readOnly: true +{% if version > (1, 0) %} web_url: title: Web url type: string format: uri readOnly: true +{% endif %} project: $ref: '#/components/schemas/ProjectEmbedded' name: @@ -1889,11 +1910,13 @@ components: type: string format: uri readOnly: true +{% if version > (1, 0) %} web_url: title: Web url type: string format: uri readOnly: true +{% endif %} msgid: title: Msgid type: string @@ -1926,11 +1949,13 @@ components: type: string format: uri readOnly: true +{% if version > (1, 0) %} web_url: title: Web url type: string format: uri readOnly: true +{% endif %} msgid: title: Msgid type: string @@ -2040,11 +2065,13 @@ components: type: string format: uri readOnly: true +{% if version > (1, 0) %} web_url: title: Web url type: string format: uri readOnly: true +{% endif %} name: title: Name description: An optional name to associate with the series, e.g. "John's PCI @@ -2177,4 +2204,4 @@ components: type: string readOnly: true servers: -- url: 'https://patchwork.ozlabs.org/api/1.1' +- url: 'https://patchwork.ozlabs.org/api/{{ "%d.%d"|format(*version) }}'