Add information about default headers

_data/api-swagger.yaml

@@ -11,18 +11,34 @@ schemes:
 produces:
   - application/json
 parameters:
-  AppkeyParam:
-    name: Application
-    description: The APPKey
+  AcceptHeader:
+    name: Accept
     in: header
     type: string
-    required: true
-  ApiKeyParam:
+    default: application/vnd.signhost.v1+json
+    description: |
+      The Signhost Api client version number.
+      Used for endpoints that produce JSON output.
+
+securityDefinitions:
+  AppKeyHeader:
+    name: Application
+    type: apiKey
+    in: header
+    description: |
+      The appkey that is generated at signup.
+      The value must be formatted as: `APPKey {Appkey}`
+  ApiKeyHeader:
     name: Authorization
-    description: The usertoken
+    type: apiKey
     in: header
-    type: string
-    required: true
+    description: |
+      Your usertoken, can be generated in the Signhost portal.
+      The value must be formatted as: `APIKey {usertoken}`
+
+security:
+  - ApiKeyHeader: []
+    AppKeyHeader: []
 
 paths:
   '/api/transaction/{transactionId}':
@@ -32,6 +48,7 @@ paths:
 
         Please do not use any GET method for active polling, but use our [postback service](/postback/) for this end.
       parameters:
+        - $ref: '#/parameters/AcceptHeader'
         - name: transactionId
           description: ID of the transaction
           in: path
@@ -59,6 +76,7 @@ paths:
         When a transaction is in an end-state the transaction the transaction will be cleaned.
         The status of the transaction will remain the same but we will clean any uploaded documents and sensitive data as soon as possible.
       parameters:
+        - $ref: '#/parameters/AcceptHeader'
         - name: transactionId
           type: string
           description: ID of the transaction
@@ -126,6 +144,7 @@ paths:
     post:
       description: Creates a new transaction
       parameters:
+        - $ref: '#/parameters/AcceptHeader'
         - in: body
           name: transaction
           description: Transaction to be added
@@ -159,6 +178,7 @@ paths:
         - 'application/pdf'
         - 'application/json'
       parameters:
+        - $ref: '#/parameters/AcceptHeader'
         - name: transactionId
           description: ID of an existing -- not yet started -- transaction
           in: path
@@ -264,7 +284,7 @@ definitions:
                 Authentications must be performed before the document(s) can be viewed.
 
                 You **must** explicitly specify the API-version when using this feature.
-                This is done with the header: 'Accept: application/vnd.signhost.v1+json'.
+                This is done with the <a href="##/parameters/AcceptHeader">Accept header</a>: 'Accept: application/vnd.signhost.v1+json'.
               type: array
               items:
                 $ref: '#/definitions/Authentication'

endpoints.html

@@ -9,6 +9,52 @@
   <p>All input strings should be UTF-8 encoded, our response is always UTF-8 encoded.</p>
   <p>Some of our endpoints return both the status of the transaction and signer activities. Further details about the statuses and activities can be found <a href="/status-activity/">here</a>.</p>
 
+  <!-- Begin list of HTTP headers-->
+    <h3>HTTP headers:</h3>
+    <p>
+        In order to communicate with the Signhost API, we expect certain HTTP headers for most endpoints.
+        The following table contains infromation about these default headers.
+    </p>
+    <table>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Default</th>
+            <th>Description</th>
+          </tr>
+        </thead>
+        <tbody>
+        <!-- Parameters -->
+        {% for p in site.data.api-swagger.parameters %}
+          {% for parameter in p %}
+            {% assign parameter = p[1] %}
+            {% if parameter.in == 'header' %}
+              <tr id="#/parameters/{{ p[0] }}"></tr>
+                <td>{{ parameter.name }}</td>
+                <td>{{ parameter.default }}</td>
+                <td>{{ parameter.description }}</td>
+              </tr>
+            {% endif %}
+          {% endfor %}
+        {% endfor %}
+        <!-- security -->
+        {% for sd in site.data.api-swagger.securityDefinitions %}
+          {% for parameter in sd %}
+            {% assign parameter = p[1] %}
+            {% if parameter.in == 'header' %}
+              <tr>
+                <td>{{ parameter.name }}</td>
+                <td>{{ parameter.default }}</td>
+                <td>{{ parameter.description | markdownify}}</td>
+              </tr>
+            {% endif %}
+          {% endfor %}
+        {% endfor %}
+      </tbody>
+    </table>
+    <br>
+    <!-- End list of all HTTP headers -->
+
   <!-- Begin list of all endpoints-->
   <h3>All endpoints:</h3>
   <ul class="endpoint_list">
@@ -60,19 +106,21 @@ <h3>Parameters</h3>
         <tbody>
 
         {% for p in method.parameters %}
-          <tr>
-            <td>{{ p.name }}</td>
-            <td>{{ p.in }}</td>
-            <td>{{ p.required }}</td>
-            <td>{{ p.description }}
-                {% if p.schema["$ref"] %}
-                  <a href="#{{ p.schema["$ref"] | uri_escape }}">
-                  {{ p.schema["$ref"] }}
-                  </a>
-                {% endif %}
-
-          </td>
-          </tr>
+          {% if p["$ref"] == null %}
+            <tr>
+              <td>{{ p.name }}</td>
+              <td>{{ p.in }}</td>
+              <td>{{ p.required }}</td>
+              <td>{{ p.description }}
+                  {% if p.schema["$ref"] %}
+                    <a href="#{{ p.schema["$ref"] | uri_escape }}">
+                    {{ p.schema["$ref"] }}
+                    </a>
+                  {% endif %}
+
+              </td>
+            </tr>
+          {% endif %}
         {% endfor %}
         </tbody>
       </table>