openapi schema gen

[jarjk]

aka swagger

see #29

eg

{
  "openapi": "3.0.0",
  "info": {
    "title": "svr-bj",
    "version": "0.1.0"
  },
  "paths": {
    "/": {
      "get": {
        "description": "index, redirect to git repo",
        "operationId": "index",
        "responses": {
          "500": {
            "description": ""
          }
        }
      }
    },
    "/bet/{username}": {
      "post": {
        "description": "make a bet of `amount` for `username` requires a game waiting for bet of `username` `bet` shall be non-zero, but shouldn't exceed user wealth deals and so might end the game with a blackjack returns game state",
        "operationId": "bet",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "uint16",
              "minimum": 0.0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Game"
                }
              }
            }
          },
          "default": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/game_state/{username}": {
      "get": {
        "description": "get the game state of a specific `username`",
        "operationId": "game_state_of",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Game"
                }
              }
            }
          },
          "404": {
            "description": ""
          }
        }
      }
    },
    "/join": {
      "get": {
        "description": "join the game as `username` if already joined and finished playing, rejoins NOTE: currently each game has it's own dealer",
        "operationId": "join",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "default": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/move/{username}": {
      "post": {
        "description": "make a [`move`](MoveAction) for `username` requires a previously made [bet] might end the game returns game state",
        "operationId": "make_move",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "action",
            "in": "query",
            "description": "what a user can do during their turn",
            "required": true,
            "schema": {
              "description": "what a user can do during their turn",
              "type": "string",
              "enum": [
                "Hit",
                "Stand"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Game"
                }
              }
            }
          },
          "default": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Card": {
        "description": "A single playing card with a rank and suit.",
        "type": "object",
        "required": [
          "rank",
          "suit"
        ],
        "properties": {
          "rank": {
            "$ref": "#/components/schemas/Rank"
          },
          "suit": {
            "$ref": "#/components/schemas/Suit"
          }
        }
      },
      "Game": {
        "description": "a game between one player and one dealer",
        "type": "object",
        "required": [
          "dealer",
          "player",
          "state"
        ],
        "properties": {
          "dealer": {
            "$ref": "#/components/schemas/Hand"
          },
          "player": {
            "$ref": "#/components/schemas/Player"
          },
          "state": {
            "$ref": "#/components/schemas/State"
          }
        }
      },
      "Hand": {
        "description": "Represents a player's or dealer's hand.",
        "type": "object",
        "required": [
          "cards"
        ],
        "properties": {
          "cards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Card"
            }
          }
        }
      },
      "Player": {
        "description": "Represents a player.",
        "type": "object",
        "required": [
          "bet",
          "hand",
          "wealth"
        ],
        "properties": {
          "bet": {
            "type": "integer",
            "format": "uint16",
            "minimum": 0.0
          },
          "hand": {
            "$ref": "#/components/schemas/Hand"
          },
          "wealth": {
            "type": "integer",
            "format": "uint16",
            "minimum": 0.0
          }
        }
      },
      "Rank": {
        "description": "Represents the 13 ranks of a card.",
        "type": "string",
        "enum": [
          "Two",
          "Three",
          "Four",
          "Five",
          "Six",
          "Seven",
          "Eight",
          "Nine",
          "Ten",
          "Jack",
          "Queen",
          "King",
          "Ace"
        ]
      },
      "State": {
        "description": "state of one game waiting for bet, ongoing, winner",
        "type": "string",
        "enum": [
          "WaitingBet",
          "Ongoing",
          "PlayerJack",
          "DealerJack",
          "PlayerBust",
          "DealerBust",
          "PlayerWin",
          "DealerWin",
          "Push"
        ]
      },
      "Suit": {
        "description": "Represents the four suits of a card deck.",
        "type": "string",
        "enum": [
          "Hearts",
          "Diamonds",
          "Clubs",
          "Spades"
        ]
      }
    }
  }
}