docs(deviceauth): migration to OpenAPI3

Changelog: None
Ticket: MEN-7714
Signed-off-by: Peter Grzybowski <peter@northern.tech>

backend/services/deviceauth/Makefile

@@ -2,4 +2,23 @@ COMPONENT := deviceauth
 
 override TESTFLAGS := $(TESTFLAGS) -p 1
 
+DOCFILES := $(wildcard docs/*_api.yml)
+MAKEDIR := $(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
+
+tests/%: docs/%.yml
+	[ -e $@ ] && rm -r $@; \
+	docker run --rm -t -v $(MAKEDIR):/work -w /work \
+		--ulimit nofile=65536:65536 \
+		-u $(shell id -u):$(shell id -g) \
+		openapitools/openapi-generator-cli:v4.3.1 generate \
+		-g python -i $< \
+		-c tests/.openapi-generator.yml \
+		-o $(dir $@) \
+		--additional-properties=packageName=$*
+
+.PHONY: docs
+docs: $(patsubst docs/%.yml,tests/%,$(DOCFILES))
+
+test_acceptance_run_deps := docs
+
 include ../Makefile.common

backend/services/deviceauth/docs/devices_api.yml

@@ -1,35 +1,18 @@
-swagger: '2.0'
+openapi: 3.0.0
 info:
-  version: '1'
-  title: Device authentication
+  version: '1.0'
+  title: Device Authentication
   description: |
     An API for device authentication handling. Intended for use by devices.
+servers:
+  - url: https://hosted.mender.io/api/devices/v1/authentication
 
-basePath: '/api/devices/v1/authentication'
-host: 'hosted.mender.io'
-schemes:
-  - https
-
-securityDefinitions:
-  DeviceJWT:
-    type: apiKey
-    in: header
-    name: Authorization
-    description: |
-      API token issued by Device Authentication service.
-      Format: 'Authorization: Bearer [JWT]'
-
-consumes:
-  - application/json
-produces:
-  - application/json
+security:
+  - DeviceJWT: []
 
 paths:
   /auth_requests:
     post:
-      operationId: Authenticate Device
-      tags:
-        - Device API
       summary: Submit an authentication request
       description: |
         The device presents its unique identity data and public key, and signs the request with its private key.
@@ -41,21 +24,23 @@ paths:
         A subsequent authentication request will reflect this decision.
 
         Note that when the JWT expires, the device must renew the JWT by sending a new authentication request.
+      operationId: Authenticate Device
+      tags:
+        - Device API
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AuthRequest'
       parameters:
-        - name: AuthRequest
-          in: body
-          description: Authentication request.
-          required: true
-          schema:
-            $ref: "#/definitions/AuthRequest"
         - name: X-MEN-Signature
           in: header
+          required: true
           description: |
             Request signature.
-
-            The request signature depends on the public key submitted in the
-            AuthRequest. A summary of signature algorithms and format follows:
-
+            The request signature depends on the public key submitted in the AuthRequest.
+            A summary of signature algorithms and format follows:
             | Type       | Digest              | Format                   | Algorithm    |
             |------------|---------------------|--------------------------|--------------|
             | RSA        | SHA256(AuthRequest) | Base64(Signature)        | [RFC2313]    |
@@ -65,76 +50,86 @@ paths:
             For ECDSA, the signature constitutes two integers (R and S)
             in which case the binary signature is taken as the ASN.1 sequence of
             the two numbers in the given order.
-          required: true
-          type: string
-      produces:
-        - application/json
-        - application/jwt
-      responses:
-        200:
-          description: Authentication successful - a new JWT is issued and returned.
           schema:
             type: string
-            example: |
+      responses:
+        '200':
+          description: Authentication successful - a new JWT is issued and returned.
+          content:
+            application/json:
+              schema:
+                type: string
+                example: |
                   eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzYxMTkxMzYsImp0aSI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2MWNlN2E4NCIsImlzcyI6Ik1lbmRlciIsInN1YiI6IjlmNzM2YmNiMjhiZmFhOTg5YjVmNWUxNDA5ZGJmMGVhYzdhNjYxMjZiNjMyZDAzYWYwZmUzNGFjMjhiZjRhNzIifQ.PArg_WuoQkOiJ4kDoHYbQRjnxykeF1lIlsgJfUryhivnip2AHz5bkxxaxF20XTq9mIzSDonTSukfOtkaxJTZXjCMHjgh50iwa6_pUivIYWsIJW2O9t_M9T_SC-7Xu7IhE_iKQFb2NXxVfAG4nZKrheUM4MJBt8SxCawT2EOPopiLeIC6MOFBu_sPa9RsagKSZCRaLTBWVhmEGbfn19tLOX3Z06DZql61G-VY-YuyOlBjpEsCc4HiA1cXIdncCZKugrONOa44_m4yx0VsgRg4jCd2VO-Is-A96Jw3zkZshoD2cPXVSKAhFdhHja447ftuYYRq9kIQghKi3hfsPgyFZQ
-        400:
+        '400':
           description: Missing or malformed request parameters or body.
-          schema:
-            $ref: '#/definitions/Error'
-          examples:
+          content:
             application/json:
-              error: "missing required parameter: id_data"
-              request_id: "f7881e82-0492-49fb-b459-795654e7188f"
-        401:
-          description: |
-                The device cannot be granted authentication. See the error message for details.
-          schema:
-            $ref: '#/definitions/Error'
-          examples:
-              application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                error: "missing required parameter: id_data"
+                request_id: "f7881e82-0492-49fb-b459-795654e7188f"
+        '401':
+          description: The device cannot be granted authentication. See the error message for details.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
                 error: "device unauthorized"
                 request_id: "f7881e82-0492-49fb-b459-795654e7188a"
-        500:
+        '500':
           description: Internal server error.
-          schema:
-            $ref: '#/definitions/Error'
-          examples:
+          content:
             application/json:
-              error: "internal error"
-              request_id: "f7881e82-0492-49fb-b459-795654e7188d"
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                error: "internal error"
+                request_id: "f7881e82-0492-49fb-b459-795654e7188d"
+
+components:
+  securitySchemes:
+    DeviceJWT:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        API token issued by Device Authentication service.
+        Format: 'Authorization: Bearer [JWT]'
+  schemas:
+    AuthRequest:
+      type: object
+      required:
+        - id_data
+        - pubkey
+      properties:
+        id_data:
+          type: string
+          description: Vendor-specific JSON representation of the device identity data (MACs, serial numbers, etc.).
+        pubkey:
+          type: string
+          description: >
+            The device's public key (PEM encoding), generated by the device or
+            pre-provisioned by the vendor. Currently supported public algorithms
+            are: RSA, Ed25519 and ECDSA P-256.
+        tenant_token:
+          type: string
+          description: Tenant token.
+      example:
+        id_data: '{"mac":"00:01:02:03:04:05"}'
+        pubkey: "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n"
+    Error:
+      type: object
+      properties:
+        error:
+          type: string
+          description: Description of the error.
+        request_id:
+          type: string
+          description: Request ID (same as in X-MEN-RequestID header).
+      example:
+        error: "error description goes here"
+        request_id: "f7881e82-0492-49fb-b459-795654e71877"
 
-definitions:
-  AuthRequest:
-    type: object
-    properties:
-      id_data:
-        type: string
-        description: Vendor-specific JSON representation of the device identity data (MACs, serial numbers, etc.).
-      pubkey:
-        type: string
-        description: >
-          The device's public key (PEM encoding), generated by the device or
-          pre-provisioned by the vendor. Currently supported public algorithms
-          are: RSA, Ed25519 and ECDSA P-256.
-      tenant_token:
-        type: string
-        description: Tenant token.
-    required:
-      - id_data
-      - pubkey
-    example:
-      id_data: "{\"mac\":\"00:01:02:03:04:05\"}"
-      pubkey: "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n"
-  Error:
-    description: Error descriptor.
-    type: object
-    properties:
-      error:
-        description: Description of the error.
-        type: string
-      request_id:
-        description: Request ID (same as in X-MEN-RequestID header).
-        type: string
-    example:
-      error: "error description goes here"
-      request_id: "f7881e82-0492-49fb-b459-795654e71877"