[PATCH 05/17] docs: Start documenting API using OpenAPI

[Stephen Finucane]

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 at that.guru>
---
 docs/api/schemas/patchwork.yaml | 76 +++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 docs/api/schemas/patchwork.yaml

diff --git a/docs/api/schemas/patchwork.yaml b/docs/api/schemas/patchwork.yaml
new file mode 100644
index 00000000..804d0c3f
--- /dev/null
+++ b/docs/api/schemas/patchwork.yaml
@@ -0,0 +1,76 @@
+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 at 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
+servers:
+- url: 'https://patchwork.ozlabs.org/api/1.1'
-- 
2.17.2