Add information about default headers

Evidos · Oct 13, 2020 · ab2c5a0 · ab2c5a0
1 parent edc6211
commit ab2c5a0
Show file tree

Hide file tree

Showing 4 changed files with 86 additions and 22 deletions.
diff --git a/_data/api-swagger.yaml b/_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 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'

diff --git a/_includes/httpheaders.html b/_includes/httpheaders.html
@@ -0,0 +1,39 @@
+<!-- Begin list of HTTP headers-->
+<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] }}">
+						<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>
+<!-- End list of all HTTP headers -->
diff --git a/endpoints.html b/endpoints.html
@@ -60,19 +60,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>

diff --git a/index.md b/index.md
@@ -33,6 +33,9 @@ A name for the usertoken has to be submitted, after which the value for this use
 The amount of usertokens that can be generated for an account is limited to 64.
 If more usertokens are needed, this needs to be requested at support@signhost.com.
 
+### HTTP Headers
+{% include httpheaders.html %}
+
 Below you find a HTTP request header example:
 
     Content-Type: application/json