openAPI primer

flask_be/OpenAPI/openapi.yaml

@@ -0,0 +1,74 @@
+openapi: 3.0.0
+info:
+  title: Flask API
+  version: 1.0.0
+paths:
+  /simple_get_query:
+    post:
+      summary: Basic queries
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                queryList:
+                  type: array
+                  items:
+                    type: string
+                cooccorrenze:
+                  type: boolean
+      responses:
+        '200':
+          description: Successful response
+        '500':
+          description: Internal server error
+  /get_context:
+    post:
+      summary: Call function for multiple contexts
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                queryList:
+                  type: array
+                  items:
+                    type: string
+                listResults:
+                  type: array
+                  items:
+                    type: object
+              required:
+                - queryList
+                - listResults
+      responses:
+        '200':
+          description: Successful response
+        '500':
+          description: Internal server error
+  /get_single_context:
+    post:
+      summary: Call function for single context
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                elem:
+                  type: string
+                params:
+                  type: object
+              required:
+                - elem
+                - params
+      responses:
+        '200':
+          description: Successful response
+        '500':
+          description: Internal server error

flask_be/OpenAPI/openapi_altro.yaml

@@ -0,0 +1,36 @@
+openapi: 3.0.0
+info:
+  title: Dariah Virtuoso Prototype
+  version: 1.0.0
+  description: GET endpoint to retrieve Dariah.it-owned semantic data via SPARQL queries
+servers:
+  - url: http://dev.restore.ovi.cnr.it:8890
+paths:
+  /sparql:
+    get:
+      summary: Execute a SPARQL query
+      description: |
+        This endpoint allows you to execute SPARQL queries against the API.
+
+        *Note:* Make sure to include the necessary query parameters in the request URL.
+
+      parameters:
+        - name: query
+          in: query
+          description: The SPARQL query to execute
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+              example:
+                result: "Query result goes here"
+        '400':
+          description: Invalid request
+        '500':
+          description: Internal server error

flask_be/OpenAPI/tictactoe.yaml

@@ -0,0 +1,182 @@
+openapi: 3.1.0
+info:
+  title: Tic Tac Toe
+  description: |
+    This API allows writing down marks on a Tic Tac Toe board
+    and requesting the state of the board or of individual squares.
+  version: 1.0.0
+tags:
+  - name: Gameplay
+paths:
+  # Whole board operations
+  /board:
+    get:
+      summary: Get the whole board
+      description: Retrieves the current state of the board and the winner.
+      tags:
+        - Gameplay
+      operationId: get-board
+      responses:
+        "200":
+          description: "OK"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/status"
+      security:
+        apiKey: []
+        app2AppOauth:
+        - board:read
+
+  # Single square operations
+  /board/{row}/{column}:
+    parameters:
+      - $ref: "#/components/parameters/rowParam"
+      - $ref: "#/components/parameters/columnParam"
+    get:
+      summary: Get a single board square
+      description: Retrieves the requested square.
+      tags:
+        - Gameplay
+      operationId: get-square
+      responses:
+        "200":
+          description: "OK"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/mark"
+        "400":
+          description: The provided parameters are incorrect
+          content:
+            text/html:
+              schema:
+                $ref: "#/components/schemas/errorMessage"
+              example: "Illegal coordinates"
+      security:
+        bearerHttpAuthentication: []
+        user2AppOauth:
+        - board:read
+    put:
+      summary: Set a single board square
+      description: Places a mark on the board and retrieves the whole board and the winner (if any).
+      tags:
+        - Gameplay
+      operationId: put-square
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/mark"
+      responses:
+        "200":
+          description: "OK"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/status"
+        "400":
+          description: The provided parameters are incorrect
+          content:
+            text/html:
+              schema:
+                $ref: "#/components/schemas/errorMessage"
+              examples:
+                illegalCoordinates:
+                  value: "Illegal coordinates."
+                notEmpty:
+                  value: "Square is not empty."
+                invalidMark:
+                  value: "Invalid Mark (X or O)."
+      security:
+        bearerHttpAuthentication: []
+        user2AppOauth:
+        - board:write
+
+components:
+  parameters:
+    rowParam:
+      description: Board row (vertical coordinate)
+      name: row
+      in: path
+      required: true
+      schema:
+        $ref: "#/components/schemas/coordinate"
+    columnParam:
+      description: Board column (horizontal coordinate)
+      name: column
+      in: path
+      required: true
+      schema:
+        $ref: "#/components/schemas/coordinate"
+  schemas:
+    errorMessage:
+      type: string
+      maxLength: 256
+      description: A text message describing an error
+    coordinate:
+      type: integer
+      minimum: 1
+      maximum: 3
+      example: 1
+    mark:
+      type: string
+      enum: [".", "X", "O"]
+      description: Possible values for a board square. `.` means empty square.
+      example: "."
+    board:
+      type: array
+      maxItems: 3
+      minItems: 3
+      items:
+        type: array
+        maxItems: 3
+        minItems: 3
+        items:
+          $ref: "#/components/schemas/mark"
+    winner:
+      type: string
+      enum: [".", "X", "O"]
+      description: Winner of the game. `.` means nobody has won yet.
+      example: "."
+    status:
+      type: object
+      properties:
+        winner:
+          $ref: "#/components/schemas/winner"
+        board:
+          $ref: "#/components/schemas/board"
+  securitySchemes:
+    defaultApiKey:
+      description: API key provided in console
+      type: apiKey
+      name: api-key
+      in: header
+    basicHttpAuthentication:
+      description: Basic HTTP Authentication
+      type: http
+      scheme: Basic
+    bearerHttpAuthentication:
+      description: Bearer token using a JWT
+      type: http
+      scheme: Bearer
+      bearerFormat: JWT
+    app2AppOauth:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://learn.openapis.org/oauth/2.0/token
+          scopes:
+            # Only reading the board allow with delegated access
+            board:read: Read the board
+    user2AppOauth:
+      type: oauth2
+      flows:
+        authorizationCode:
+          authorizationUrl: https://learn.openapis.org/oauth/2.0/auth
+          tokenUrl: https://learn.openapis.org/oauth/2.0/token
+          scopes:
+            # Reads and writes permitted via authorization code flow
+            board:read: Read the board
+            board:write: Write to the board