From 6d3f113c4e1a28df86c79ed46990483a55991149 Mon Sep 17 00:00:00 2001 From: Sylvain Renault Date: Fri, 4 Mar 2022 17:45:11 +0100 Subject: [PATCH 1/2] Major and minor changes. New headlines in yaml file. Reformating whoel yaml. Introduction of components/repsonses params. Some extensions in two MD files. New GET method for the end objects of a world link. --- API/openapi.yaml | 363 +++++++++++++++++++++++++++++++++-------------- README.md | 35 +++-- 2 files changed, 282 insertions(+), 116 deletions(-) diff --git a/API/openapi.yaml b/API/openapi.yaml index fa69aa7..5186d81 100644 --- a/API/openapi.yaml +++ b/API/openapi.yaml @@ -1,4 +1,17 @@ openapi: "3.0.0" +# +# API for the Augmented Reality Framework (ARF) +# Working group: ETSI ISG ARF +# STF group: STF620 (validation) +# (C) ETSI - 2022 +# +# References: +# - Explaination UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier / https://fr.wikipedia.org/wiki/Universally_unique_identifier +# - UUID formats: 8-4-4-4-12 format string, lower case (but case insensitive on input) +# - UUID RFC4122: https://datatracker.ietf.org/doc/html/rfc4122#section-3 +# - Rules for RESTful error code RFC2616: https://datatracker.ietf.org/doc/html/rfc2616#section-10 +# - Guide: https://restfulapi.net/http-status-codes/ +# info: version: 0.0.4 title: World Storage API @@ -14,26 +27,30 @@ paths: summary: Test the server availability responses: '200': - description: OK + description: OK, world storage alive. /admin: get: - summary: Get the version of the API + summary: Get the version of the API. operationId: getVersion responses: '200': - description: OK world storage. + description: OK, world storage ready. content: text/plain: schema: - type: string + type: string + +############## +# TRACKABLES # +############## /trackables: post: - summary: Create a trackable + summary: Create a trackable. operationId: addTrackable tags: - trackables requestBody: - description: the trackable to be added to the world storage + description: The trackable to be added to the world storage. required: true content: application/json: @@ -44,30 +61,27 @@ paths: $ref: '#/components/schemas/Trackable' responses: '200': - description: OK returns the UUID of the Trackable defined by the world storage. + description: OK, returns the UUID of the Trackable defined by the world storage. content: text/plain: schema: type: string '201': - description: Null response - default: - description: unexpected error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -# Check 2xx, 4xx, 5xx... - '401': - $ref: '#/components/responses/UUID' + description: Null response. + '400': + $ref: '#/components/responses/400_BadRequest' + '409': + $ref: '#/components/responses/409_NotEmptyUUID' + 'default': + $ref: '#/components/responses/4xx_UnexpectedError' get: - summary: returns the list of all trackables defined by the world storage. + summary: Returns the list of all trackables defined by the world storage. operationId: getTrackables tags: - trackables responses: '200': - description: OK returns all the Trackables defined by the world storage. + description: OK, returns all the Trackables defined by the world storage. content: application/json: schema: @@ -75,65 +89,67 @@ paths: items : $ref: "#/components/schemas/Trackable" '201': - description: Null response + description: Null response. default: - description: unexpected error - content: - application/json: - schema: - $ref: "#/components/schemas/Error" + $ref: '#/components/responses/4xx_UnexpectedError' /trackables/{trackableUUID}: get: - summary: Find a trackable by its UUID + summary: Find a trackable by its UUID. operationId: getTrackableById tags: - trackables parameters: - name: trackableUUID in: path - description: UUID of the trackable to retrieve + description: UUID of the trackable to retrieve. required: true schema: type: string + format: uuid responses: '200': - description: Successful operation + description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/Trackable' '400': - description: Invalid UUID supplied + $ref: '#/components/responses/400_InvalidUUID' '404': - description: Trackable not found + $ref: '#/components/responses/404_NotFoundUUID' delete: - summary: Deletes a trackable + summary: Deletes a trackable. operationId: deleteTrackable tags: - trackables parameters: - name: trackableUUID in: path - description: trackable UUID to delete + description: Trackable UUID to delete. required: true schema: type: string + format: uuid responses: '200': - description: OK + description: OK, delete successful. '400': - description: Invalid UUID supplied + $ref: '#/components/responses/400_InvalidUUID' '404': - description: trackable not found + $ref: '#/components/responses/404_NotFoundUUID' + +################# +# WORLD ANCHORS # +################# /worldAnchors: post: - summary: Create a world anchor + summary: Create a world anchor. operationId: addWorldAnchor tags: - world anchors requestBody: - description: the world anchor to be added to the world storage + description: The world anchor to be added to the world storage. required: true content: application/json: @@ -144,92 +160,95 @@ paths: $ref: '#/components/schemas/WorldAnchor' responses: '200': - description: OK returns the UUID of the World Anchor defined by the world storage. + description: OK, returns the UUID of the World Anchor defined by the world storage. content: text/plain: schema: type: string '201': - description: Null response - default: - description: unexpected error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + description: Null response. + '400': + $ref: '#/components/responses/400_BadRequest' + '409': + $ref: '#/components/responses/409_NotEmptyUUID' + 'default': + $ref: '#/components/responses/4xx_UnexpectedError' get: - summary: returns the list of all world anchors defined by the world storage. + summary: Returns the list of all world anchors defined by the world storage. operationId: getWorldAnchors tags: - world anchors responses: - 200: - description: OK returns all the world anchors defined by the world storage. + '200': + description: OK, returns all the world anchors defined by the world storage. content: application/json: schema: type : array items : $ref: "#/components/schemas/WorldAnchor" - 201: - description: Null response + '201': + description: Null response. default: - description: unexpected error - content: - application/json: - schema: - $ref: "#/components/schemas/Error" + $ref: '#/components/responses/4xx_UnexpectedError' + /worldAnchors/{worldAnchorUUID}: get: - summary: Find a world anchor by his UUID + summary: Find a world anchor by its UUID. operationId: getWorldAnchorById tags: - world anchors parameters: - - name: trackableUUID + - name: worldAnchorUUID in: path - description: UUID of the world anchor to retrieve + description: UUID of the world anchor to retrieve. required: true schema: type: string + format: uuid responses: '200': - description: Successful operation + description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/WorldAnchor' '400': - description: Invalid UUID supplied + $ref: '#/components/responses/400_InvalidUUID' '404': - description: World Anchor not found + $ref: '#/components/responses/404_NotFoundUUID' delete: - summary: Deletes a world anchor + summary: Deletes a world anchor. operationId: deleteWorldAnchor tags: - world anchors parameters: - - name: trackableUUID + - name: worldAnchorUUID in: path - description: world anchor UUID to delete + description: World anchor UUID to delete. required: true schema: type: string + format: uuid responses: '200': - description: OK + description: OK, delete successful. '400': - description: Invalid UUID supplied + $ref: '#/components/responses/400_InvalidUUID' '404': - description: World anchor not found + $ref: '#/components/responses/404_NotFoundUUID' + +############### +# WORLD LINKS # +############### /worldLinks: post: - summary: Create a link between world anchors and trackables + summary: Create a link between world anchors and trackables. operationId: addWorldLink tags: - world links requestBody: - description: the link to be added to the world storage + description: The link to be added to the world storage. required: true content: application/json: @@ -240,26 +259,26 @@ paths: $ref: '#/components/schemas/WorldLink' responses: '200': - description: OK returns the UUID of the link defined by the world storage. + description: OK, returns the UUID of the link defined by the world storage. content: text/plain: schema: type: string '201': description: Null response - default: - description: unexpected error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + '400': + $ref: '#/components/responses/400_BadRequest' + '409': + $ref: '#/components/responses/409_NotEmptyUUID' + 'default': + $ref: '#/components/responses/4xx_UnexpectedError' get: - summary: returns the list of all links defined by the world storage. + summary: Returns the list of all links defined by the world storage. operationId: getWorldLinks tags: - world links responses: - 200: + '200': description: OK returns all the worldLinks defined by the world storage. content: application/json: @@ -267,40 +286,38 @@ paths: type : array items : $ref: "#/components/schemas/WorldLink" - 201: + '201': description: Null response default: - description: unexpected error - content: - application/json: - schema: - $ref: "#/components/schemas/Error" + $ref: '#/components/responses/4xx_UnexpectedError' + /worldLinks/{worldLinkUUID}: get: - summary: Find a link by his ID + summary: Find a link by its UUID. operationId: getWorldLinkById tags: - world links parameters: - name: worldLinkUUID in: path - description: ID of the link to retrieve + description: UUID of the link to retrieve. required: true schema: type: string + format: uuid responses: '200': - description: Successful operation + description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/WorldLink' '400': - description: Invalid ID supplied + $ref: '#/components/responses/400_InvalidUUID' '404': - description: World Link not found + $ref: '#/components/responses/404_NotFoundUUID' delete: - summary: Deletes a worldLink + summary: Deletes a worldLink. operationId: deleteWorldLink tags: - world links @@ -311,14 +328,60 @@ paths: required: true schema: type: string + format: uuid responses: '200': description: OK '400': - description: Invalid ID supplied + $ref: '#/components/responses/400_InvalidUUID' + '404': + $ref: '#/components/responses/404_NotFoundUUID' + + /worldLinks/attached/{worldLinkUUID}: + get: + summary: Retrieve end objects connected to this world link by its UUID. + operationId: getAttachedObjectsFromUUID + tags: + - world links + parameters: + - name: worldLinkUUID + in: path + description: UUID of the link from which you will retrieve the end objects. + required: true + schema: + type: string + format: uuid + responses: + '200': + description: Successful operation. + content: + application/json: + schema: + $ref: '#/components/schemas/AttachedObjects' + '400': + $ref: '#/components/responses/400_InvalidUUID' '404': - description: link not found + $ref: '#/components/responses/404_NotFoundUUID' + +# COMPONENTS ############################################### components: + #------------------------------- + # Reusable operation parameters + #------------------------------- + parameters: + UUIDParams: + name: UUID + in: path + required: true + description: A Universally Unique IDentifier identifying the object + schema: + type: string + format: uuid + default: "00000000-0000-0000-0000-000000000000" + + #------------------------------- + # Reusable schemas (data models) + #------------------------------- schemas: Trackable: type: object @@ -333,17 +396,17 @@ components: - keyvalueTagList properties: UUID: - description: A Universally Unique IDentifier identifying the trackable (RFC 4122) + description: A Universally Unique IDentifier identifying the trackable (RFC 4122). type: string format: uuid example: fa8bbe40-8052-11ec-a8a3-0242ac120002 creatorUUID: - description: A Universally Unique IDentifier identifying the creator of the trackable (a person, a team or a company) + description: A Universally Unique IDentifier identifying the creator of the trackable (a person, a team or a company). type: string format: uuid example: c75f6324-77a0-11ec-90d6-0242ac120003 trackableType: - description: Extensible list of trackable types possibly handled by complient World Storage implementation + description: Extensible list of trackable types possibly handled by complient World Storage implementation. type: string enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, OTHER] example: FIDUCIAL_MARKER @@ -362,6 +425,7 @@ components: $ref: '#/components/schemas/Size' keyvalueTags: $ref: '#/components/schemas/KeyvalueTagList' + WorldAnchor: type: object required: @@ -372,12 +436,12 @@ components: - keyvalueTagList properties: UUID: - description: A Universally Unique IDentifier identifying the world anchor + description: A Universally Unique IDentifier identifying the world anchor (RFC 4122). type: string format: uuid example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002 creatorUUID: - description: A Universally Unique IDentifier identifying the creator of the world anchor + description: A Universally Unique IDentifier identifying the creator of the world anchor. type: string format: uuid example: c75f6324-77a0-11ec-90d6-0242ac120003 @@ -389,6 +453,7 @@ components: $ref: '#/components/schemas/Size' keyvalueTags: $ref: '#/components/schemas/KeyvalueTagList' + WorldLink: type: object required: @@ -401,22 +466,22 @@ components: - keyvalueTags properties: UUID: - description: A Universally Unique IDentifier identifying the link + description: A Universally Unique IDentifier identifying the link (RFC 4122). type: string format: uuid example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002 creatorUUID: - description: A Universally Unique IDentifier identifying the creator of the link + description: A Universally Unique IDentifier identifying the creator of the link. type: string format: uuid example: c75f6324-77a0-11ec-90d6-0242ac120003 UUIDFrom: - description: A Universally Unique IDentifier identifying a world anchor or trackable + description: A Universally Unique IDentifier identifying a world anchor or trackable. type: string format: uuid example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002 UUIDTo: - description: A Universally Unique IDentifier identifying a world anchor or trackable + description: A Universally Unique IDentifier identifying a world anchor or trackable. type: string format: uuid example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002 @@ -429,7 +494,37 @@ components: keyvalueTags: description: List of additional parameters to be stored $ref: '#/components/schemas/KeyvalueTagList' - example: { "LinkType" : ["Hierarchy"]} + example: { "LinkType" : ["Hierarchy"]} + + AttachedObjects: + type: object + required: + - UUID + - UUIDFrom + - UUIDTo + - TypeFrom + - TypeTo + properties: + UUID: + description: A Universally Unique IDentifier identifying the link. + type: string + format: uuid + example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002 + UUIDFrom: + description: A Universally Unique IDentifier identifying a world anchor or trackable. + type: string + format: uuid + example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002 + UUIDTo: + description: A Universally Unique IDentifier identifying a world anchor or trackable. + type: string + format: uuid + example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002 + TypeFrom: + $ref: '#/components/schemas/ObjectType' + TypeTo: + $ref: '#/components/schemas/ObjectType' + EncodingInformationStructure: required: - dataFormat @@ -444,6 +539,7 @@ components: 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 @@ -456,20 +552,29 @@ components: 4, 4, 4, 2, 1, 0,-2, 1, -1,-2, 0, 0] + + ObjectType: + description: Type of an world representaion object. + type: string + enum: [Trackable, WorldAnchor, WorldLink] + example: Trackable + UnitSystem: - description: Unit of length + description: Unit of length. type: string enum: [MM, CM, DM, M, DAM, HM, KM, INCH, FOOT, YARD, MILE] example: M + Size: - description: Size {width, length, depth} + description: Size {width, length, depth}. type: array items: type: number format: double minItems: 3 maxItems: 3 - example: [1,5,0] + example: [1,5,0] + KeyvalueTagList: description: List of additional parameters to be stored with the trackable. type: object @@ -479,6 +584,7 @@ components: type: string minItems: 1 example: { "Place" : ["Museum 1"], "room" : ["B4"]} + Error: required: - code @@ -489,3 +595,50 @@ components: format: int32 message: type: string + #------------------------------- + # Reusable responses + #------------------------------- + responses: + ####################### + # 1xx : Informational # + ####################### + + ################# + # 2xx : Success # + ################# + + ##################### + # 3xx : Redirection # + ##################### + + ####################### + # 4xx : Client Errors # + ####################### + 400_BadRequest: + description: Bad request. + + 400_InvalidUUID: + description: Invalid UUID supplied. + + 404_NotFoundUUID: + description: Not found, could not find UUID in database. + + 409_NotEmptyUUID: + description: Invalid UUID, id must be a Nil value. + + 4xx_UnexpectedError: # Can be referenced as '#/components/responses/GenericError' + description: Unexpected error. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + ######################## + # 5xx : Server Errors # + ######################## + 5xx_UnexpectedError: + description: Unexpected server error. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' diff --git a/README.md b/README.md index 51e23fc..a45f4c5 100644 --- a/README.md +++ b/README.md @@ -97,24 +97,37 @@ Contains temporary office documents that are edited collaboratively and all othe - Visual Studio - Visual Studio Code -- Unity 3D +- Unity 3D (Version 2020.3 LTS) -# 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. +# Creating Server/Client Code -We consider 5 categories of branches: -- **develop**: collects the different features. While it is recommended that this branch be as stable as possible, each commit is not considered as a release, but much more as a pre-release. -- **feature**: dedicated to the development of features (named ***feature/*** *featureName*). These feature branches allow to share code among developers working on a common feature. When a feature is implemented, it must be tested before merging it to the develop branch with a pull request. When a feature branch is merged into develop, it must be suppress from the reposiory. It is recommended that the develop branch be merged into the feature branches on a regular basis to avoid any drift. -- **master**: corresponds to the last version of stable code. The develop branch is merged in the master branch when a release is ready. Bug fixes from release branches are also merged is the master branch when useful. -- **release**: dedicated to the releases. One branch per minor version release must be created (named ***release/*** *major_minor_patch*), and a tag must be set. When a bug is fixed on a release, it should be merge is the release branch. Then a new tag is created by increasing the patch digit of the release version. -- **bug**: dedicated to the bug fix of releases (named ***bug/*** *bugID*). +## Tool: openapi-generator -Branching strategy +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. +Find a description here: https://openapi-generator.tech/docs/usage/ +Install the tool with "npm", see: https://openapi-generator.tech/docs/installation/ +### Help +> npx @openapitools/openapi-generator-cli help +### Validating the api + +> npx @openapitools/openapi-generator-cli validate -i .\openapi.yaml + +### Example C++ Server (Pistache) + +> npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g cpp-pistache-server -o ./codeGeneration/sever/cpp/pistache + +### Example ASP.NET Server (C#) + +> npx @openapi-generator-cli generate -i openapi.yaml -g aspnetcore -o ./codeGeneration/server/aspnetcore + +### Example C# Client + +> npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g csharp-netcore -o ./codeGeneration/client/c#/netcore # 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. @@ -126,7 +139,7 @@ We consider 5 categories of branches: - **release**: dedicated to the releases. One branch per minor version release must be created (named ***release/*** *major_minor_patch*), and a tag must be set. When a bug is fixed on a release, it should be merge is the release branch. Then a new tag is created by increasing the patch digit of the release version. - **bug**: dedicated to the bug fix of releases (named ***bug/*** *bugID*). -Branching strategy +Branching strategy -- GitLab From 322e9997607e5ea9583cad3b3b359a6730be1159 Mon Sep 17 00:00:00 2001 From: Sylvain Renault Date: Fri, 4 Mar 2022 18:26:22 +0100 Subject: [PATCH 2/2] Referecing new components/responses params. Some corrections in the main MD file. Commenting "application/xml" block while this create some warnings in the generator. --- API/openapi.yaml | 21 ++++++++++++--------- README.md | 8 ++++---- 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/API/openapi.yaml b/API/openapi.yaml index 5186d81..1c8de72 100644 --- a/API/openapi.yaml +++ b/API/openapi.yaml @@ -12,6 +12,8 @@ openapi: "3.0.0" # - Rules for RESTful error code RFC2616: https://datatracker.ietf.org/doc/html/rfc2616#section-10 # - Guide: https://restfulapi.net/http-status-codes/ # +# Last Version: 04.03.2022 +# info: version: 0.0.4 title: World Storage API @@ -25,6 +27,7 @@ paths: /ping: get: summary: Test the server availability + operationId: getPing responses: '200': description: OK, world storage alive. @@ -56,9 +59,9 @@ paths: application/json: schema: $ref: '#/components/schemas/Trackable' - application/xml: - schema: - $ref: '#/components/schemas/Trackable' + #application/xml: + # schema: + # $ref: '#/components/schemas/Trackable' responses: '200': description: OK, returns the UUID of the Trackable defined by the world storage. @@ -155,9 +158,9 @@ paths: application/json: schema: $ref: '#/components/schemas/WorldAnchor' - application/xml: - schema: - $ref: '#/components/schemas/WorldAnchor' + #application/xml: + # schema: + # $ref: '#/components/schemas/WorldAnchor' responses: '200': description: OK, returns the UUID of the World Anchor defined by the world storage. @@ -254,9 +257,9 @@ paths: application/json: schema: $ref: '#/components/schemas/WorldLink' - application/xml: - schema: - $ref: '#/components/schemas/WorldLink' + #application/xml: + # schema: + # $ref: '#/components/schemas/WorldLink' responses: '200': description: OK, returns the UUID of the link defined by the world storage. diff --git a/README.md b/README.md index a45f4c5..1012339 100644 --- a/README.md +++ b/README.md @@ -115,19 +115,19 @@ Install the tool with "npm", see: https://openapi-generator.tech/docs/installati ### Validating the api -> npx @openapitools/openapi-generator-cli validate -i .\openapi.yaml +> npx @openapitools/openapi-generator-cli validate -i API/openapi.yaml ### Example C++ Server (Pistache) -> npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g cpp-pistache-server -o ./codeGeneration/sever/cpp/pistache +> npx @openapitools/openapi-generator-cli generate -i API/openapi.yaml -g cpp-pistache-server -o ./CodeGeneration/sever/cpp/pistache ### Example ASP.NET Server (C#) -> npx @openapi-generator-cli generate -i openapi.yaml -g aspnetcore -o ./codeGeneration/server/aspnetcore +> npx @openapitools/openapi-generator-cli generate -i API/openapi.yaml -g aspnetcore -o ./CodeGeneration/server/aspnetcore ### Example C# Client -> npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g csharp-netcore -o ./codeGeneration/client/c#/netcore +> npx @openapitools/openapi-generator-cli generate -i API/openapi.yaml -g csharp -o ./CodeGeneration/client/csharp # 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. -- GitLab