From 7d8e24bc84bd0c73643822944b3c7dc901ee8b41 Mon Sep 17 00:00:00 2001
From: Stephen Finucane <stephen@that.guru>
Date: Fri, 26 Oct 2018 21:42:02 +0100
Subject: docs: Start documenting API using OpenAPI

When the REST API was first added, we attempted to document it using
OpenAPI 2.0 (formerly Swagger). This was mostly never completed because
(a) it was really tedious and (b) no one was that bothered. However, as
we expand the range of clients for the REST API, having a well
documented API becomes more and more of an asset.

Start doing this by adding a brand new schema, this time using OpenAPI.
This will entirely replace the older schema and, as such, is namespaced
separately. We start by documenting '/' (i.e. the index) page and will
add additional resources as we go.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 docs/api/schemas/patchwork.yaml | 74 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 docs/api/schemas/patchwork.yaml

(limited to 'docs')

diff --git a/docs/api/schemas/patchwork.yaml b/docs/api/schemas/patchwork.yaml
new file mode 100644
index 0000000..515dac3
--- /dev/null
+++ b/docs/api/schemas/patchwork.yaml
@@ -0,0 +1,74 @@
+openapi: '3.0.0'
+info:
+  title: Patchwork API
+  description: |
+    Patchwork is a web-based patch tracking system designed to facilitate the
+    contribution and management of contributions to an open-source project.
+  contact:
+    email: patchwork@lists.ozlabs.org
+  license:
+    name: GPL v2 License
+    url: https://www.gnu.org/licenses/gpl-2.0.html
+  version: '1.1'
+paths:
+  /api/:
+    get:
+      description: List API resources.
+      operationId: api_list
+      parameters: []
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Index'
+      tags:
+      - api
+components:
+  securitySchemes:
+    basicAuth:
+      type: http
+      scheme: basic
+    apiKeyAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    Index:
+      type: object
+      properties:
+        bundles:
+          title: Bundles URL
+          type: string
+          format: uri
+          readOnly: true
+        covers:
+          title: Covers URL
+          type: string
+          format: uri
+          readOnly: true
+        events:
+          title: Events URL
+          type: string
+          format: uri
+          readOnly: true
+        patches:
+          title: Patches URL
+          type: string
+          format: uri
+          readOnly: true
+        people:
+          title: People URL
+          type: string
+          format: uri
+          readOnly: true
+        projects:
+          title: Projects URL
+          type: string
+          format: uri
+          readOnly: true
+        users:
+          title: Users URL
+          type: string
+          format: uri
+          readOnly: true
-- 
cgit v1.2.3