Commit 99ea877d authored by Jerome Royan's avatar Jerome Royan
Browse files

Merge branch 'fix/generator_issues' into 'main' 

Issues with title in get endpoints solved.

See merge request !6
parents 073fd721 57348800

API/common/commonopenapi.yaml

+269 −220
Original line number Diff line number Diff line 






# Copyright 2022 ETSI. Licensed under the BSD-3-Clause license

# API for the Augmented Reality Framework (ARF)

# Working group: ETSI ISG ARF

# STF group: STF620 (validation)

#

# 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

# - online UUID generator: https://www.uuidgenerator.net/

# - Rules for RESTful error code RFC2616: https://datatracker.ietf.org/doc/html/rfc2616#section-10

# - Guide: https://restfulapi.net/http-status-codes/

#

# Last Version: 06.09.2024



openapi: 3.0.0



info: 

  version: 2.0.0

  title: Common module for ARF API

  description: Common components for the World Storage and the World Analysis services

  license:

    name: BSD-3-clause

    url: https://opensource.org/licenses/BSD-3-Clause



# COMPONENTS ###############################################

components:
@@ -72,21 +91,22 @@ 


    Token:

      type: string

        example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuYXV0aDAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tL2NhbGFuZGFyL3YxLyIsInN1YiI6InVzcl8xMjMiLCJpYXQiOjE0NTg3ODU3OTYsImV4cCI6MTQ1ODg3MjE5Nn0.CA7eaHjIHz5NxeIJoFK9krqaeZrPLwmMmgI_XiQiIkQ

      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

      description: A string representing the token of the User.



    Success:

      type: object

      properties:

        message:

          type: string

          example: "Success 2xx"



    Error:

        required:

          - code

          - message

      type: object

      properties:

          code:

            type: integer

            format: int32

            example: 406

        message:

          type: string

            example: "Error 406"

          example: "Error 4xx"



    SessionID:

      type: string
@@ -128,7 +148,6 @@ 
    Capability:

      description: An object representing a supported capability of the World Analysis and its associated metadata

      type: object

        uniqueItems: true

      properties:

        trackableType:

          $ref: '#/components/schemas/TrackableType'
@@ -158,6 +177,21 @@ 
      #################

      # 2xx : Success #

      #################

      200_SuccessRequest:

        description: Success request.

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/Success'

              example: "Success request"

      

      200_UuidResponse:

        description: OK, return the UUID of the Trackable defined by the world storage.

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/Success'

              example: "777266da-e286-11ec-8fea-0242ac120002"



      #####################

      # 3xx : Redirection #
@@ -169,49 +203,57 @@ 
      400_BadRequest:

        description: Bad request.

        content:

            text/plain:

          application/json:

            schema:

                type: string

              $ref: '#/components/schemas/Error'

              example: "Bad request"



      400_InvalidUUID:

        description: Invalid UUID supplied.

        content:

            text/plain:

          application/json:

            schema:

              $ref: '#/components/schemas/Error'

              example: "The format of the UUID is incorrect"

                type: string



      401_NullResponse: 

        description: Null response.

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/Error'

              example: "Null response"



      403_Forbidden:

        description: Not allowed.

        content: 

            text/plain:

          application/json:

            schema:

                type: string

              $ref: '#/components/schemas/Error'

              example: "Not allowed"

              

      404_NotFound:

        description: Not found.

        content:

            text/plain:

          application/json:

            schema:

                type: string

              $ref: '#/components/schemas/Error'

              example: "Not found"



      404_NotFoundUUID:

        description: Not found, could not find UUID in database.

        content:

            text/plain:

          application/json:

            schema:

                type: string

              $ref: '#/components/schemas/Error'

              example: "Element not found"

                

      405_NotSupported:

        description: Not supported.

        content:

            text/plain:

          application/json:

            schema:

                type: string

              $ref: '#/components/schemas/Error'

              example: "Not supported"        



      4xx_UnexpectedError:      # Can be referenced as '#/components/responses/GenericError'
@@ -224,14 +266,21 @@ 
      409_NotEmptyUUID:

        description: Invalid UUID, id must be a Nil value.

        content: 

            text/plain:

          application/json:

            schema:

                type: string

              $ref: '#/components/schemas/Error'

              example: "The element you sent has already a value and can't be sent to the world storage"



      ########################

      # 5xx : Server Errors  #

      ########################

      511_InvalidToken:

        description: The secret token is not valid. Please ask an ISG ARF team member for a valid token.

        content: 

          application/json:

            schema:

              $ref: '#/components/schemas/Error'



      5xx_UnexpectedError:

        description: Unexpected server error.

        content:

API/worldanalysis/worldanalysisopenapi.yaml

+54 −12
Original line number Diff line number Diff line 
# Copyright 2022 ETSI. Licensed under the BSD-3-Clause license

# API for the Augmented Reality Framework (ARF)

# Working group: ETSI ISG ARF

# STF group: STF620 (validation)

#

# 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

# - online UUID generator: https://www.uuidgenerator.net/

# - Rules for RESTful error code RFC2616: https://datatracker.ietf.org/doc/html/rfc2616#section-10

# - Guide: https://restfulapi.net/http-status-codes/

#

# Last Version: 06.09.2024



openapi: "3.0.0"



info: 

  version: 2.0.1

  version: 2.0.0

  title: World Analysis API

  description: API ensuring interoperability between Scene Management and a World Analysis service

  license:

    name: BSD-3-clause

    url: https://opensource.org/licenses/BSD-3-Clause

servers:

  - url: https://localhost:44301

  - url: http://localhost:8080

  - url: https://analysis.etsi.hhi.fraunhofer.de



tags:

  - name: default
@@ -19,7 +36,6 @@ tags: 
    description : Operation to retrieves the supported capabilities of the World Analysis



paths:

## Default

  /ping:

    get:

      summary: Test the server availability.
@@ -57,6 +73,9 @@ paths: 
                type: string

                example: "1.0.0"



#################

# Configuration #

#################

  /pose/configure/framerate:

    post:

      summary: Specify the a minimum frame rate for pose estimation for Trackable types
@@ -84,9 +103,14 @@ paths: 
          description: Successful operation.

        '405':

          $ref: '../common/commonopenapi.yaml#/components/responses/405_NotSupported'       

        '511':

          $ref: '../common/commonopenapi.yaml#/components/responses/511_InvalidToken'       

        'default':

          $ref: '../common/commonopenapi.yaml#/components/responses/4xx_UnexpectedError'



#########

# Poses #

#########

  /pose/{trackableOrAnchorUUID}:

    get:

      summary: Request the last pose of a single Anchor or Trackable
@@ -132,6 +156,8 @@ paths: 
          $ref: '../common/commonopenapi.yaml#/components/responses/404_NotFound'

        '405':

          $ref: '../common/commonopenapi.yaml#/components/responses/405_NotSupported'    

        '511':

          $ref: '../common/commonopenapi.yaml#/components/responses/511_InvalidToken'       

        'default':

          $ref: '../common/commonopenapi.yaml#/components/responses/4xx_UnexpectedError'
@@ -160,6 +186,7 @@ paths: 
          uniqueItems: true

          items:

            type: object

            title: UuidAndMode

            properties:

              uuid:

                type: string
@@ -178,6 +205,7 @@ paths: 
            application/json:

              schema:

                type: object

                title: Poses

                properties:

                  poses:

                    type: array
@@ -191,6 +219,8 @@ paths: 
          $ref: '../common/commonopenapi.yaml#/components/responses/404_NotFound'

        '405':

          $ref: '../common/commonopenapi.yaml#/components/responses/405_NotSupported'    

        '511':

          $ref: '../common/commonopenapi.yaml#/components/responses/511_InvalidToken'       

        'default':

          $ref: '../common/commonopenapi.yaml#/components/responses/4xx_UnexpectedError'
@@ -236,6 +266,8 @@ paths: 
          $ref: '../common/commonopenapi.yaml#/components/responses/404_NotFound'

        '405':

          $ref: '../common/commonopenapi.yaml#/components/responses/405_NotSupported'

        '511':

          $ref: '../common/commonopenapi.yaml#/components/responses/511_InvalidToken'       

        'default':

          $ref: '../common/commonopenapi.yaml#/components/responses/4xx_UnexpectedError'
@@ -275,6 +307,8 @@ paths: 
          $ref: '../common/commonopenapi.yaml#/components/responses/400_BadRequest'

        '404':

          $ref: '../common/commonopenapi.yaml#/components/responses/404_NotFound'

        '511':

          $ref: '../common/commonopenapi.yaml#/components/responses/511_InvalidToken'       

    put:

      summary: Update a subscription

      operationId: updateSubscription
@@ -328,6 +362,8 @@ paths: 
          $ref: '../common/commonopenapi.yaml#/components/responses/400_BadRequest'

        '404':

          $ref: '../common/commonopenapi.yaml#/components/responses/404_NotFound'

        '511':

          $ref: '../common/commonopenapi.yaml#/components/responses/511_InvalidToken'       

    delete:

        summary: Remove a subscription to a given pose

        operationId: unsubscribeFromPose
@@ -353,17 +389,17 @@ paths: 
            example: "bdc83e6b-a89d-4b29-9c99-e9015d448b10"

        responses:

          '200':

            description: OK, unsubcription successful.

            content:

              text/plain:

                schema:

                  type: string

                  example: "Subscription succesfuly deleted"

            $ref: '../common/commonopenapi.yaml#/components/responses/200_SuccessRequest'

          '400':

            $ref: '../common/commonopenapi.yaml#/components/responses/400_BadRequest'

          '404':

            $ref: '../common/commonopenapi.yaml#/components/responses/404_NotFound'

          '511':

            $ref: '../common/commonopenapi.yaml#/components/responses/511_InvalidToken'       



################

# Capabilities #

################

  /capabilities:

    get:

      summary: Get the supported capabilities of the World Analysis
@@ -387,11 +423,14 @@ paths: 
            application/json:

              schema:

                type: object

                title: Capabilities

                properties:

                  capabilities:

                    type: array

                    items: 

                      $ref: '../common/commonopenapi.yaml#/components/schemas/Capability'

        '511':

          $ref: '../common/commonopenapi.yaml#/components/responses/511_InvalidToken'       

        'default':

          $ref: '../common/commonopenapi.yaml#/components/responses/4xx_UnexpectedError'
@@ -426,6 +465,7 @@ paths: 
              application/json:

                schema:

                  type: object

                  title: Supports

                  properties:

                    type:

                      $ref: '../common/commonopenapi.yaml#/components/schemas/TypeWorldStorage'
@@ -441,6 +481,8 @@ paths: 
            $ref: '../common/commonopenapi.yaml#/components/responses/404_NotFound'

          '405':

            $ref: '../common/commonopenapi.yaml#/components/responses/405_NotSupported'

          '511':

            $ref: '../common/commonopenapi.yaml#/components/responses/511_InvalidToken'       

          'default':

            $ref: '../common/commonopenapi.yaml#/components/responses/4xx_UnexpectedError'
@@ -565,7 +607,6 @@ components: 
    PoseConfiguration:

      description: An object representing the framerate that the World Analysis needs to reach for a given Trackable Type

      type: object

      uniqueItems: true

      properties:

        trackableType:

          type: string
@@ -611,9 +652,10 @@ components: 
          description: List of UUID of the Trackable or Anchor to subscribe

          type: array

          items:

            type: string

            format: uuid

          example: [ "fa8bbe40-8052-11ec-a8a3-0242ac120002", "fa8bbe40-8052-11ec-a8a3-0242ac120003"]

        mode:

        modes:

          description: List of modes representing the context of the Relocalization information (AR device to WorldAnchor/Trackable or WorldAnchor/Trackable to AR device)

          type: array

          items:
@@ -629,7 +671,7 @@ components: 
          example: "http://myscenemanagementserver.com/poses"

      required:

        - targets

        - mode

        - modes



    SubscriptionSingle:

      description: Response when subscribing for pose update of a Trackable or a WorldAnchor

API/worldstorage/worldstorageopenapi.yaml

+84 −119

File changed.

Preview size limit exceeded, changes collapsed.