API/common/commonopenapi.yaml

+
+
+
+
+  openapi: 3.0.0
+
+    
+# COMPONENTS ###############################################
+  components:
+
+    #-------------------------------
+    # Reusable schemas (data models)
+    #-------------------------------
+    schemas:
+
+        Mode_WorldAnalysis:
+          description: Mode representing the context of the relocalization information (AR device to WorldAnchor/Trackable or WorldAnchor/Trackable to AR device)
+          type: string
+          enum: [TRACKABLES_TO_DEVICE, DEVICE_TO_TRACKABLES]
+          example: TRACKABLES_TO_DEVICE
+        
+        Mode_WorldStorage:
+          description: Mode representing the context of the relocalization information (AR device to WorldAnchor/Trackable or WorldAnchor/Trackable to AR device)
+          type: string
+          enum: [TRACKABLES_TO_REQUEST, REQUEST_TO_TRACKABLES]
+          example: TRACKABLES_TO_REQUEST
+        
+        EncodingInformationStructure:
+          description: An object holding the info of a Trackable`'`s encoding information `:` the data format and the version.
+          required:
+            - dataFormat
+            - version
+          properties:
+            dataFormat:
+              description: Identifier of the target framework.
+              type: string
+              enum: [HOLOLENS, ARKIT, ARCORE, VUFORIA, ARUCO, OTHER]
+              example : "HOLOLENS"
+            version:
+              description: The version of the format
+              type: string
+              example : "1.01"
+
+        Transform3D:
+            description: Coordinate reference system of the world anchor, a 4*4 matrix (rowmajor) represented by a float vector.
+            type: array
+            minItems: 16
+            maxItems: 16
+            items:
+              type: number
+              format: float
+            example: [ 1, 0, 0, 3,
+                      0, 1, 0, 3,
+                      0, 0, 1, 3,
+                      0, 0, 0, 1]
+
+        UnitSystem:
+            description: Unit of length.
+            type: string
+            enum: [MM,  CM,  DM,  M,  DAM,  HM,  KM,  INCH, FOOT, YARD, MILE]
+            example: M
+
+        Size:
+            description: Size object in format {width, length, depth}.
+            type: array
+            items:
+                type: number
+                format: double
+            minItems: 3
+            maxItems: 3
+            example: [1.0,1.0,1.5]   
+
+        Token:
+          type: string
+          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuYXV0aDAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tL2NhbGFuZGFyL3YxLyIsInN1YiI6InVzcl8xMjMiLCJpYXQiOjE0NTg3ODU3OTYsImV4cCI6MTQ1ODg3MjE5Nn0.CA7eaHjIHz5NxeIJoFK9krqaeZrPLwmMmgI_XiQiIkQ
+          description: A string representing the token of the User.
+
+        Error:
+          required:
+            - code
+            - message
+          properties:
+            code:
+              type: integer
+              format: int32
+              example: 406
+            message:
+              type: string
+              example: "Error 406"
+            
+        SessionID:
+          type: string
+          example: 4JA1xVJSYKE47UM7RKDrfUcTXlJ0wxSQ
+          description: A string representing the session ID associated with the AR session.
+
+        Pose:
+          description: An element representing the result of the pose estimation of an AR device, a Trackable or a WorldAnchor by the World Analysis
+          type: object
+          properties:
+            uuid:
+              description: UUID of the associated Anchor or Trackable
+              type: string
+              format: uuid
+              example: "fa8bbe40-8052-11ec-a8a3-0242ac120002"
+            estimationState:
+              description: Extensible List of possible states of the pose estimation
+              type: string
+              enum: [OK, FAILURE]
+              example: OK
+            instructionInfo:
+              description: A message detailing the context of the pose estimation
+              type: string
+              example: Lighting is toom dim
+            timestamp:
+              description: Capture time of the pose as number of milliseconds since unix epoch
+              type: integer
+              example : 1704812114841
+            confidence: 
+              description: A score representing the confidence concerning the accuracy of the pose estimated
+              type: number
+              example : 50.00
+            mode:
+              description: Mode representing the context of the Relocalization information (AR device to WorldAnchor/Trackable or WorldAnchor/Trackable to AR device)
+              $ref: '#/components/schemas/Mode_WorldAnalysis'
+            value:
+              description: The pose value
+              oneOf:
+                - $ref: '#/components/schemas/MatrixPoseValue'
+                - $ref: '#/components/schemas/VectorQuaternionPoseValue'
+                - $ref: '#/components/schemas/GeodeticPoseValue'
+              example:
+                type: "MATRIX"
+                transform: [ 1, 0, 0, 3,
+                  0, 1, 0, 3,
+                  0, 0, 1, 3,
+                  0, 0, 0, 1 ]
+            subscriptionUrl:
+              description: The URL to use for subscription (if available), see [/pose/subscriptions]
+              type: string
+              example: "http://mywordanalysisserver.com/pose/subscriptions?target=fa8bbe40-8052-11ec-a8a3-0242ac120002"
+            
+        PoseValue:
+          description: Base type to define the pose value
+          type: object
+          properties:
+            type:
+              description: Encoding type of the Pose
+              type: string
+              enum: [MATRIX, VECTOR_QUATERNION, GEODETIC]
+        
+        MatrixPoseValue:
+          description: A pose value that is described with a 4*4 matrix
+          allOf:     #inheritance
+            - $ref: '#/components/schemas/PoseValue'
+          properties:    
+            transform: 
+              description : Pose data
+              $ref: '#/components/schemas/Transform3D'
+            unit:
+              description: Unit system of the pose
+              $ref: '#/components/schemas/UnitSystem'
+
+        VectorQuaternionPoseValue:
+          description: A pose value that is described with a position and a rotation
+          allOf:     #inheritance
+              - $ref: '#/components/schemas/PoseValue'
+          properties:
+            position: 
+              description : Pose Position
+              $ref: '#/components/schemas/Vector3'
+            rotation: 
+              description : Pose Rotation
+              $ref: '#/components/schemas/Quaternion'  
+            unit:
+              description: Unit system of the pose
+              $ref: '#/components/schemas/UnitSystem'      
+
+        GeodeticPoseValue:
+          description : A pose value in a geodetic coordinate system
+          allOf:     #inheritance
+            - $ref: '#/components/schemas/PoseValue'
+          properties:
+            altitude: 
+              type: number
+              example: 70.0
+            longitude:
+              type: number
+              example: 7.013579
+            latitude: 
+              type: number
+              example: 43.57351
+            rotation:  
+              description: Pose Rotation
+              $ref: '#/components/schemas/Quaternion'
+            geodeticsystem:
+              description: Associated geodetic system of the pose
+              type: string
+              example: "WGS84"
+            rotationTarget:
+                description: Coordinate system of the rotation
+                type : string
+                enum: [EASTUPSOUTH, WESTUPNORTH]
+                example: EASTUPSOUTH
+        
+        Vector3:
+          description: A 3 coordinates vector
+          type: array
+          minItems: 3
+          maxItems: 3
+          items:
+            type: number
+            format: float
+          example: [ 1, 0, 0 ]
+
+        Quaternion:
+          description: A quaternion
+          type: array
+          minItems: 4
+          maxItems: 4
+          items:
+            type: number
+            format: float
+          example: [ 0, 0, 0, 1 ]
+
+        TypeWorldStorage:
+          description: Trackable or Anchor
+          type: string
+          enum: [TRACKABLE, ANCHOR]
+          example: ANCHOR
+
+        Capability:
+          description: An object representing a supported capability of the World Analysis and its associated metadata
+          type: object
+          uniqueItems: true
+          properties:
+            trackableType:
+              type: string
+              enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, GEOPOSE, OTHER]
+              example: "FIDUCIAL_MARKER"
+            encodingInformation:
+              $ref: '#/components/schemas/EncodingInformationStructure' 
+            framerate: 
+              description: Number of frames per second the tracking of this type of trackable is performed by the World Analysis
+              type: number
+              example : 30.0
+            latency:
+              description: Mean tracking latency in milliseconds for this type of trackable 
+              type: number 
+              example: 10.0
+            accuracy:
+              description: Accuracy score for the detection of this type of Trackable by the World Analysis
+              type: number 
+              example: 50.0
+    
+      #-------------------------------
+      # Reusable responses
+      #-------------------------------
+    responses:
+        #######################
+        # 1xx : Informational #
+        #######################
+
+        #################
+        # 2xx : Success #
+        #################
+
+        #####################
+        # 3xx : Redirection #
+        #####################
+
+        #######################
+        # 4xx : Client Errors #
+        #######################
+        400_BadRequest:
+          description: Bad request.
+          content:
+            text/plain:
+              schema:
+                type: string
+                example: "Bad request"
+
+        400_InvalidUUID:
+          description: Invalid UUID supplied.
+          content:
+            text/plain:
+              schema:
+                example: "The format of the UUID is incorrect"
+                type: string
+
+        403_Forbidden:
+          description: Not allowed.
+          content:
+            text/plain:
+              schema:
+                type: string
+                example: "Not allowed"
+                
+        404_NotFound:
+          description: Not found.
+          content:
+            text/plain:
+              schema:
+                type: string
+                example: "Not found"
+
+        404_NotFoundUUID:
+          description: Not found, could not find UUID in database.
+          content:
+            text/plain:
+              schema:
+                type: string
+                example: "Element not found"
+                  
+        405_NotSupported:
+          description: Not supported.
+          content:
+            text/plain:
+              schema:
+                type: string
+                example: "Not supported"        
+
+        4xx_UnexpectedError:      # Can be referenced as '#/components/responses/GenericError'
+          description: Unexpected error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+        409_NotEmptyUUID:
+          description: Invalid UUID, id must be a Nil value.
+          content:
+            text/plain:
+              schema:
+                type: string
+                example: "The element you sent has already a value and can't be sent to the world storage"
+
+        ########################
+        # 5xx : Server Errors  #
+        ########################
+        5xx_UnexpectedError:
+          description: Unexpected server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'

README.md

-
 - [Objectives](#objectives)
 - [Associated workspaces](#associated-workspaces)
   - [Overview and fast access](#overview-and-fast-access)
@@ -92,18 +91,19 @@ Contains temporary office documents that are edited collaboratively and all othe
 - Codegen
   - [Swagger Codegen](https://swagger.io/tools/swagger-codegen/)
   - [Swagger Codegen documentation](https://swagger.io/docs/open-source-tools/swagger-codegen/)
+  - [NSwag](https://github.com/RicoSuter/NSwag)
 
 ## Development tools
 
 - Visual Studio
 - Visual Studio Code
-- Unity 3D (Version 2020.3 LTS)
+- Unity 3D (Version 2022.3 LTS)
 
 # Creating Server/Client Code
 
 ## Tool: openapi-generator
 
-We recommand the usage of the open source command-line tool **openapi-generator** while it has a good compatibility to API v3.x and produces accurate source code, similar to Swagger.
+We recommand the usage of the open source command-line tool **openapi-generator** while it has a good compatibility to API v3.x and produces accurate source code, similar to Swagger. Special for C# project and especially for code generation for Unity (C# scripts) we recommand th useage of the free tool **NSwag**. NSwag create a light-weight code  
 
 Find a description here: https://openapi-generator.tech/docs/usage/
 
@@ -115,19 +115,30 @@ Install the tool with "npm", see: https://openapi-generator.tech/docs/installati
 
 ### Validating the api
 
-> npx @openapitools/openapi-generator-cli validate -i API/openapi.yaml
+> npx @openapitools/openapi-generator-cli validate -i API/worldanalysis/worldanalysisopenapi.yaml
+
+> npx @openapitools/openapi-generator-cli validate -i API/worldstorage/worldstorageopenapi.yaml
+
+If you need some recommandations, use the option: `--recommand`
+
+### Creating the code for server or client
+
+Without any arguments, the openapi-generator-cli uses the configuration found in the file `openapitools.json`.
+Run this command in a shell.
+
+> npx @openapitools/openapi-generator-cli generate
 
-### Example C++ Server (Pistache)
+You will find the correct setup files in the corresponding implementation of the RESTful interface in the ETSI GitLab.
 
-> npx @openapitools/openapi-generator-cli generate -i API/openapi.yaml  -g cpp-pistache-server -o ./CodeGeneration/sever/cpp/pistache
+### Creating lightweight C# code with NSwag
 
-### Example ASP.NET Server (C#)
+You have to setup NSwag through a json or xml configuration file, here e.g. a file `nswag.json` and run this in a shell:
 
-> npx @openapitools/openapi-generator-cli generate -i API/openapi.yaml -g aspnetcore -o ./CodeGeneration/server/aspnetcore
+> npx nswag run nswag.json
 
-### Example C# Client
+You will find the correct setup files in the corresponding implementation of the RESTful interface in the ETSI GitLab.
 
-> npx @openapitools/openapi-generator-cli generate -i API/openapi.yaml  -g csharp -o ./CodeGeneration/client/csharp
+Rem: The code (one module) can directly be used in a Unity project, after implementing the Web interface for the communication.
 
 # Branching Policy
 Distributed version control systems like Git offers developers great flexibility to share and manage code. But a branching policy is crucial to collaborate more easily while keeping track of releases with bug fixes.