tictactoe

JSON

{
  "openapi": "3.1.0",
  "info": {
    "title": "Tic Tac Toe",
    "description": "This API allows writing down marks on a Tic Tac Toe board\nand requesting the state of the board or of individual squares.\n",
    "version": "1.0.0"
  },
  "tags": [
    {
      "name": "Gameplay"
    }
  ],
  "paths": {
    "/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": [
          {
            "defaultApiKey": []
          },
          {
            "app2AppOauth": ["board:read"]
          }
        ]
      }
    },
    "/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": {
              "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": {
              "board:read": "Read the board",
              "board:write": "Write to the board"
            }
          }
        }
      }
    }
  }
}

YAML

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:
        - defaultApiKey: []
        - 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