file upload/download docs

Author: hauner

docs/howto/file_download.md

@@ -0,0 +1,38 @@
+---
+layout: default
+title: OpenAPI: describing a file download endpoint
+parent: HowTo's
+nav_order: 10
+---
+
+Describing an endpoint to download file attachments.
+
+```yaml
+    /v1/attachments/{id}:
+      get:
+        summary: download an attachment
+        parameters:
+          - in: path
+            name: id
+            required: true
+            schema:
+              type: integer
+              format: int64
+        responses:
+          200:
+            description: attachment data
+            headers:
+              Content-Disposition:
+                schema:
+                  type: string
+                description: the format is `attachment; filename="name.zip"`
+            content:
+              application/*:
+                schema:
+                  type: string
+                  format: binary
+              image/*:
+                schema:
+                  type: string
+                  format: binary
+```

docs/howto/file_upload.md

@@ -0,0 +1,60 @@
+---
+layout: default
+title: OpenAPI: describing a file upload endpoint
+parent: HowTo's
+nav_order: 15
+---
+
+Describing and endpoint for uploading a singe file:
+
+```yaml
+    /attachments:
+      summary: upload an attachment
+      post:
+        requestBody:
+          content:
+            multipart/form-data:
+              schema:
+                type: object
+                properties:
+                  file:
+                    type: string
+                    format: binary
+        responses:
+          204:
+            description: succesfully created attachment
+            content:
+              application/json:
+                schema:
+                  type: integer
+                  format: int64
+```
+
+Describing an endpoint for uploading multiple files:
+
+```yaml
+    /attachments:
+      summary: upload multiple attachments
+      post:
+        requestBody:
+          content:
+            multipart/form-data:
+              schema:
+                type: object
+                properties:
+                  files:
+                    type: array
+                    items:
+                      type: string
+                      format: binary
+        responses:
+          204:
+            description: succesfully created attachment
+            content:
+              application/json:
+                schema:
+                  type: array
+                  items:
+                    type: string
+                    format: int64
+```