17th-Battalion-Tracker/api/openapi.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "17th Rangers Database API",
    "description": "An API for the 17th Rangers Database",
    "contact": {
      "email": "indigo@indigofox.dev",
      "name": "Indigo Fox"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/license/mit/"
    },
    "version": "0.0.1"
  },
  "servers": [
    {
      "url": "http://localhost:3001/api",
      "description": "Development"
    },
    {
      "url": "https://indigofox.dev:9230/api",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "members",
      "description": "Operations on users/members"
    },
    {
      "name": "ranks",
      "description": "Rank information & related categories"
    },
    {
      "name": "awards",
      "description": "Badges & ribbons"
    },
    {
      "name": "courses",
      "description": "Training courses"
    },
    {
      "name": "courseEvents",
      "description": "Instances of trainings held for specific courses"
    },
    {
      "name": "member statuses",
      "description": "Member status indicating active, inactive, company membership, etc."
    }
  ],
  "paths": {
    "/members": {
      "get": {
        "tags": [
          "members"
        ],
        "summary": "Get all members",
        "description": "Returns a list of all members",
        "responses": {
          "200": {
            "description": "A list of members",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Member"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/InternalServerError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "members"
        ],
        "summary": "Create a member",
        "description": "Creates a new member",
        "requestBody": {
          "description": "Member object that needs to be added",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Member created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Member"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/ClientInputError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/InternalServerError"
                }
              }
            }
          }
        }
      }
    },
    "/members/{memberId}": {
      "get": {
        "tags": [
          "members"
        ],
        "summary": "Get a member by ID",
        "description": "Returns a single member",
        "parameters": [
          {
            "name": "memberId",
            "in": "path",
            "description": "ID of member to return",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Member found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Member"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/InternalServerError"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "members"
        ],
        "summary": "Update a member by ID",
        "description": "Updates a member",
        "parameters": [
          {
            "name": "memberId",
            "in": "path",
            "description": "ID of member to update",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "description": "Member object that needs to be updated",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Member updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Member"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/ClientInputError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/InternalServerError"
                }
              }
            }
          }
        }
      }
    },
    "/training-reports": {
      "get": {
        "tags": [
          "training-reports"
        ],
        "summary": "Get all training reports",
        "description": "Returns a list of all training reports",
        "responses": {
          "200": {
            "description": "A list of training reports",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/TrainingReport"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/InternalServerError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "training-reports"
        ],
        "summary": "Create a training report",
        "description": "Creates a new training report",
        "requestBody": {
          "$ref": "#/components/requestBodies/CourseEventTrainingReport",
          "required": true
        },
        "responses": {
          "201": {
            "description": "Training report created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrainingReport"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/ClientInputError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/InternalServerError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Member": {
        "$ref": "schemas/member.json"
      },
      "MemberPut": {
        "$ref": "schemas/memberPut.json"
      },
      "Rank": {
        "$ref": "schemas/rank.json"
      },
      "Award": {
        "$ref": "schemas/award.json"
      },
      "AwardAction": {
        "$ref": "schemas/awardAction.json"
      },
      "CourseEvent": {
        "$ref": "schemas/courseEvent.json"
      },
      "Error": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "description": "A human readable error message",
            "type": "string"
          }
        }
      }
    },
    "requestBodies": {
      "CourseEventTrainingReport": {
        "$ref": "requestBodies/courseEventTrainingReport.json"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized"
      },
      "ClientInputError": {
        "description": "Client Input Error"
      },
      "NotFound": {
        "description": "Not Found"
      },
      "InternalServerError": {
        "description": "Internal Server Error"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "plain-text"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}