From 55a107828ecd86aa89fa0d75d5af2b34b4bd8ba3 Mon Sep 17 00:00:00 2001 From: itzaname Date: Sun, 22 Jun 2025 20:00:14 -0400 Subject: [PATCH] Add missing docs --- docs/docs.go | 767 ++++++++++++++++++++++++++++++++++++++++++++++ docs/swagger.json | 742 ++++++++++++++++++++++++++++++++++++++++++++ docs/swagger.yaml | 476 ++++++++++++++++++++++++++++ 3 files changed, 1985 insertions(+) create mode 100644 docs/docs.go create mode 100644 docs/swagger.json create mode 100644 docs/swagger.yaml diff --git a/docs/docs.go b/docs/docs.go new file mode 100644 index 0000000..54e6013 --- /dev/null +++ b/docs/docs.go @@ -0,0 +1,767 @@ +// Package docs Code generated by swaggo/swag. DO NOT EDIT +package docs + +import "github.com/swaggo/swag" + +const docTemplate = `{ + "schemes": {{ marshal .Schemes }}, + "swagger": "2.0", + "info": { + "description": "{{escape .Description}}", + "title": "{{.Title}}", + "contact": {}, + "version": "{{.Version}}" + }, + "host": "{{.Host}}", + "basePath": "{{.BasePath}}", + "paths": { + "/map": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a list of maps", + "produces": [ + "application/json" + ], + "tags": [ + "maps" + ], + "summary": "List maps", + "parameters": [ + { + "maximum": 100, + "minimum": 1, + "type": "integer", + "default": 10, + "description": "Page size (max 100)", + "name": "page_size", + "in": "query" + }, + { + "minimum": 1, + "type": "integer", + "default": 1, + "description": "Page number", + "name": "page_number", + "in": "query" + }, + { + "type": "integer", + "name": "game_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/PagedResponse-Map" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/map/{id}": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a specific map by its ID", + "produces": [ + "application/json" + ], + "tags": [ + "maps" + ], + "summary": "Get map by ID", + "parameters": [ + { + "type": "integer", + "description": "Map ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/Response-Map" + } + }, + "404": { + "description": "Map not found", + "schema": { + "$ref": "#/definitions/Error" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/rank": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a list of ranks with pagination and filtering", + "produces": [ + "application/json" + ], + "tags": [ + "ranks" + ], + "summary": "List ranks", + "parameters": [ + { + "maximum": 100, + "minimum": 1, + "type": "integer", + "default": 10, + "description": "Page size (max 100)", + "name": "page_size", + "in": "query" + }, + { + "minimum": 1, + "type": "integer", + "default": 1, + "description": "Page number", + "name": "page_number", + "in": "query" + }, + { + "maximum": 2, + "minimum": 1, + "enum": [ + 1, + 2 + ], + "type": "integer", + "default": 1, + "description": "Sort by (1: rank asc, 2: skill)", + "name": "sort_by", + "in": "query" + }, + { + "type": "integer", + "name": "gameId", + "in": "query" + }, + { + "type": "integer", + "name": "modeId", + "in": "query" + }, + { + "type": "integer", + "name": "styleId", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/PagedResponse-Rank" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/time": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a list of times", + "produces": [ + "application/json" + ], + "tags": [ + "times" + ], + "summary": "List times", + "parameters": [ + { + "maximum": 100, + "minimum": 1, + "type": "integer", + "default": 10, + "description": "Page size (max 100)", + "name": "page_size", + "in": "query" + }, + { + "minimum": 1, + "type": "integer", + "default": 1, + "description": "Page number", + "name": "page_number", + "in": "query" + }, + { + "type": "integer", + "name": "game_id", + "in": "query" + }, + { + "type": "integer", + "name": "map_id", + "in": "query" + }, + { + "type": "integer", + "name": "mode_id", + "in": "query" + }, + { + "type": "integer", + "name": "style_id", + "in": "query" + }, + { + "type": "integer", + "name": "user_id", + "in": "query" + }, + { + "enum": [ + "0", + "1", + "2", + "3" + ], + "type": "string", + "default": "0", + "description": "Sort field (time ASC, time DESC, date ASC, date DESC)", + "name": "sort_by", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/PagedResponse-Time" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/time/{id}": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a specific time by its ID", + "produces": [ + "application/json" + ], + "tags": [ + "times" + ], + "summary": "Get time by ID", + "parameters": [ + { + "type": "integer", + "description": "Time ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/Response-Time" + } + }, + "404": { + "description": "Time not found", + "schema": { + "$ref": "#/definitions/Error" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/user": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a list of users", + "produces": [ + "application/json" + ], + "tags": [ + "users" + ], + "summary": "List users", + "parameters": [ + { + "maximum": 100, + "minimum": 1, + "type": "integer", + "default": 10, + "description": "Page size (max 100)", + "name": "page_size", + "in": "query" + }, + { + "minimum": 1, + "type": "integer", + "default": 1, + "description": "Page number", + "name": "page_number", + "in": "query" + }, + { + "type": "integer", + "name": "state_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/PagedResponse-User" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/user/{id}": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a specific user by their ID", + "produces": [ + "application/json" + ], + "tags": [ + "users" + ], + "summary": "Get user by ID", + "parameters": [ + { + "type": "integer", + "description": "User ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/Response-User" + } + }, + "404": { + "description": "User not found", + "schema": { + "$ref": "#/definitions/Error" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/user/{id}/rank": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a specific rank for a user by their ID", + "produces": [ + "application/json" + ], + "tags": [ + "users" + ], + "summary": "Get rank by user ID", + "parameters": [ + { + "type": "integer", + "description": "User ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "integer", + "name": "gameId", + "in": "query" + }, + { + "type": "integer", + "name": "modeId", + "in": "query" + }, + { + "type": "integer", + "name": "styleId", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/Response-User" + } + }, + "404": { + "description": "User not found", + "schema": { + "$ref": "#/definitions/Error" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + } + }, + "definitions": { + "Error": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + }, + "Map": { + "type": "object", + "properties": { + "creator": { + "type": "string" + }, + "date": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "game_id": { + "type": "integer" + }, + "id": { + "type": "integer" + } + } + }, + "PagedResponse-Map": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "type": "array", + "items": { + "$ref": "#/definitions/Map" + } + }, + "pagination": { + "description": "Pagination contains information about paging", + "allOf": [ + { + "$ref": "#/definitions/Pagination" + } + ] + } + } + }, + "PagedResponse-Rank": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "type": "array", + "items": { + "$ref": "#/definitions/Rank" + } + }, + "pagination": { + "description": "Pagination contains information about paging", + "allOf": [ + { + "$ref": "#/definitions/Pagination" + } + ] + } + } + }, + "PagedResponse-Time": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "type": "array", + "items": { + "$ref": "#/definitions/Time" + } + }, + "pagination": { + "description": "Pagination contains information about paging", + "allOf": [ + { + "$ref": "#/definitions/Pagination" + } + ] + } + } + }, + "PagedResponse-User": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "type": "array", + "items": { + "$ref": "#/definitions/User" + } + }, + "pagination": { + "description": "Pagination contains information about paging", + "allOf": [ + { + "$ref": "#/definitions/Pagination" + } + ] + } + } + }, + "Pagination": { + "type": "object", + "properties": { + "page": { + "description": "Current page number", + "type": "integer" + }, + "page_size": { + "description": "Number of items per page", + "type": "integer" + }, + "total_items": { + "description": "Total number of items across all pages", + "type": "integer" + }, + "total_pages": { + "description": "Total number of pages", + "type": "integer" + } + } + }, + "Rank": { + "type": "object", + "properties": { + "game_id": { + "type": "integer" + }, + "id": { + "type": "integer" + }, + "mode_id": { + "type": "integer" + }, + "rank": { + "type": "number" + }, + "skill": { + "type": "number" + }, + "style_id": { + "type": "integer" + }, + "updated_at": { + "type": "string" + }, + "user": { + "$ref": "#/definitions/User" + } + } + }, + "Response-Map": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "allOf": [ + { + "$ref": "#/definitions/Map" + } + ] + } + } + }, + "Response-Time": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "allOf": [ + { + "$ref": "#/definitions/Time" + } + ] + } + } + }, + "Response-User": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "allOf": [ + { + "$ref": "#/definitions/User" + } + ] + } + } + }, + "Time": { + "type": "object", + "properties": { + "date": { + "type": "string" + }, + "game_id": { + "type": "integer" + }, + "has_bot": { + "type": "boolean" + }, + "id": { + "type": "integer" + }, + "map": { + "$ref": "#/definitions/Map" + }, + "mode_id": { + "type": "integer" + }, + "style_id": { + "type": "integer" + }, + "time": { + "type": "integer" + }, + "user": { + "$ref": "#/definitions/User" + } + } + }, + "User": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "muted": { + "type": "boolean" + }, + "state_id": { + "type": "integer" + }, + "username": { + "type": "string" + } + } + } + }, + "securityDefinitions": { + "ApiKeyAuth": { + "type": "apiKey", + "name": "X-API-Key", + "in": "header" + } + } +}` + +// SwaggerInfo holds exported Swagger Info so clients can modify it +var SwaggerInfo = &swag.Spec{ + Version: "1.0", + Host: "", + BasePath: "/api/v1", + Schemes: []string{}, + Title: "StrafesNET Data API", + Description: "Obtain an api key at https://dev.strafes.net\nRequires Data:Read permission", + InfoInstanceName: "swagger", + SwaggerTemplate: docTemplate, + LeftDelim: "{{", + RightDelim: "}}", +} + +func init() { + swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo) +} diff --git a/docs/swagger.json b/docs/swagger.json new file mode 100644 index 0000000..a8d25fa --- /dev/null +++ b/docs/swagger.json @@ -0,0 +1,742 @@ +{ + "swagger": "2.0", + "info": { + "description": "Obtain an api key at https://dev.strafes.net\nRequires Data:Read permission", + "title": "StrafesNET Data API", + "contact": {}, + "version": "1.0" + }, + "basePath": "/api/v1", + "paths": { + "/map": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a list of maps", + "produces": [ + "application/json" + ], + "tags": [ + "maps" + ], + "summary": "List maps", + "parameters": [ + { + "maximum": 100, + "minimum": 1, + "type": "integer", + "default": 10, + "description": "Page size (max 100)", + "name": "page_size", + "in": "query" + }, + { + "minimum": 1, + "type": "integer", + "default": 1, + "description": "Page number", + "name": "page_number", + "in": "query" + }, + { + "type": "integer", + "name": "game_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/PagedResponse-Map" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/map/{id}": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a specific map by its ID", + "produces": [ + "application/json" + ], + "tags": [ + "maps" + ], + "summary": "Get map by ID", + "parameters": [ + { + "type": "integer", + "description": "Map ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/Response-Map" + } + }, + "404": { + "description": "Map not found", + "schema": { + "$ref": "#/definitions/Error" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/rank": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a list of ranks with pagination and filtering", + "produces": [ + "application/json" + ], + "tags": [ + "ranks" + ], + "summary": "List ranks", + "parameters": [ + { + "maximum": 100, + "minimum": 1, + "type": "integer", + "default": 10, + "description": "Page size (max 100)", + "name": "page_size", + "in": "query" + }, + { + "minimum": 1, + "type": "integer", + "default": 1, + "description": "Page number", + "name": "page_number", + "in": "query" + }, + { + "maximum": 2, + "minimum": 1, + "enum": [ + 1, + 2 + ], + "type": "integer", + "default": 1, + "description": "Sort by (1: rank asc, 2: skill)", + "name": "sort_by", + "in": "query" + }, + { + "type": "integer", + "name": "gameId", + "in": "query" + }, + { + "type": "integer", + "name": "modeId", + "in": "query" + }, + { + "type": "integer", + "name": "styleId", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/PagedResponse-Rank" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/time": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a list of times", + "produces": [ + "application/json" + ], + "tags": [ + "times" + ], + "summary": "List times", + "parameters": [ + { + "maximum": 100, + "minimum": 1, + "type": "integer", + "default": 10, + "description": "Page size (max 100)", + "name": "page_size", + "in": "query" + }, + { + "minimum": 1, + "type": "integer", + "default": 1, + "description": "Page number", + "name": "page_number", + "in": "query" + }, + { + "type": "integer", + "name": "game_id", + "in": "query" + }, + { + "type": "integer", + "name": "map_id", + "in": "query" + }, + { + "type": "integer", + "name": "mode_id", + "in": "query" + }, + { + "type": "integer", + "name": "style_id", + "in": "query" + }, + { + "type": "integer", + "name": "user_id", + "in": "query" + }, + { + "enum": [ + "0", + "1", + "2", + "3" + ], + "type": "string", + "default": "0", + "description": "Sort field (time ASC, time DESC, date ASC, date DESC)", + "name": "sort_by", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/PagedResponse-Time" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/time/{id}": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a specific time by its ID", + "produces": [ + "application/json" + ], + "tags": [ + "times" + ], + "summary": "Get time by ID", + "parameters": [ + { + "type": "integer", + "description": "Time ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/Response-Time" + } + }, + "404": { + "description": "Time not found", + "schema": { + "$ref": "#/definitions/Error" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/user": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a list of users", + "produces": [ + "application/json" + ], + "tags": [ + "users" + ], + "summary": "List users", + "parameters": [ + { + "maximum": 100, + "minimum": 1, + "type": "integer", + "default": 10, + "description": "Page size (max 100)", + "name": "page_size", + "in": "query" + }, + { + "minimum": 1, + "type": "integer", + "default": 1, + "description": "Page number", + "name": "page_number", + "in": "query" + }, + { + "type": "integer", + "name": "state_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/PagedResponse-User" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/user/{id}": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a specific user by their ID", + "produces": [ + "application/json" + ], + "tags": [ + "users" + ], + "summary": "Get user by ID", + "parameters": [ + { + "type": "integer", + "description": "User ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/Response-User" + } + }, + "404": { + "description": "User not found", + "schema": { + "$ref": "#/definitions/Error" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + }, + "/user/{id}/rank": { + "get": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "description": "Get a specific rank for a user by their ID", + "produces": [ + "application/json" + ], + "tags": [ + "users" + ], + "summary": "Get rank by user ID", + "parameters": [ + { + "type": "integer", + "description": "User ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "integer", + "name": "gameId", + "in": "query" + }, + { + "type": "integer", + "name": "modeId", + "in": "query" + }, + { + "type": "integer", + "name": "styleId", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/Response-User" + } + }, + "404": { + "description": "User not found", + "schema": { + "$ref": "#/definitions/Error" + } + }, + "default": { + "description": "General error response", + "schema": { + "$ref": "#/definitions/Error" + } + } + } + } + } + }, + "definitions": { + "Error": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + }, + "Map": { + "type": "object", + "properties": { + "creator": { + "type": "string" + }, + "date": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "game_id": { + "type": "integer" + }, + "id": { + "type": "integer" + } + } + }, + "PagedResponse-Map": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "type": "array", + "items": { + "$ref": "#/definitions/Map" + } + }, + "pagination": { + "description": "Pagination contains information about paging", + "allOf": [ + { + "$ref": "#/definitions/Pagination" + } + ] + } + } + }, + "PagedResponse-Rank": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "type": "array", + "items": { + "$ref": "#/definitions/Rank" + } + }, + "pagination": { + "description": "Pagination contains information about paging", + "allOf": [ + { + "$ref": "#/definitions/Pagination" + } + ] + } + } + }, + "PagedResponse-Time": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "type": "array", + "items": { + "$ref": "#/definitions/Time" + } + }, + "pagination": { + "description": "Pagination contains information about paging", + "allOf": [ + { + "$ref": "#/definitions/Pagination" + } + ] + } + } + }, + "PagedResponse-User": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "type": "array", + "items": { + "$ref": "#/definitions/User" + } + }, + "pagination": { + "description": "Pagination contains information about paging", + "allOf": [ + { + "$ref": "#/definitions/Pagination" + } + ] + } + } + }, + "Pagination": { + "type": "object", + "properties": { + "page": { + "description": "Current page number", + "type": "integer" + }, + "page_size": { + "description": "Number of items per page", + "type": "integer" + }, + "total_items": { + "description": "Total number of items across all pages", + "type": "integer" + }, + "total_pages": { + "description": "Total number of pages", + "type": "integer" + } + } + }, + "Rank": { + "type": "object", + "properties": { + "game_id": { + "type": "integer" + }, + "id": { + "type": "integer" + }, + "mode_id": { + "type": "integer" + }, + "rank": { + "type": "number" + }, + "skill": { + "type": "number" + }, + "style_id": { + "type": "integer" + }, + "updated_at": { + "type": "string" + }, + "user": { + "$ref": "#/definitions/User" + } + } + }, + "Response-Map": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "allOf": [ + { + "$ref": "#/definitions/Map" + } + ] + } + } + }, + "Response-Time": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "allOf": [ + { + "$ref": "#/definitions/Time" + } + ] + } + } + }, + "Response-User": { + "type": "object", + "properties": { + "data": { + "description": "Data contains the actual response payload", + "allOf": [ + { + "$ref": "#/definitions/User" + } + ] + } + } + }, + "Time": { + "type": "object", + "properties": { + "date": { + "type": "string" + }, + "game_id": { + "type": "integer" + }, + "has_bot": { + "type": "boolean" + }, + "id": { + "type": "integer" + }, + "map": { + "$ref": "#/definitions/Map" + }, + "mode_id": { + "type": "integer" + }, + "style_id": { + "type": "integer" + }, + "time": { + "type": "integer" + }, + "user": { + "$ref": "#/definitions/User" + } + } + }, + "User": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "muted": { + "type": "boolean" + }, + "state_id": { + "type": "integer" + }, + "username": { + "type": "string" + } + } + } + }, + "securityDefinitions": { + "ApiKeyAuth": { + "type": "apiKey", + "name": "X-API-Key", + "in": "header" + } + } +} \ No newline at end of file diff --git a/docs/swagger.yaml b/docs/swagger.yaml new file mode 100644 index 0000000..a3e8596 --- /dev/null +++ b/docs/swagger.yaml @@ -0,0 +1,476 @@ +basePath: /api/v1 +definitions: + Error: + properties: + error: + type: string + type: object + Map: + properties: + creator: + type: string + date: + type: string + display_name: + type: string + game_id: + type: integer + id: + type: integer + type: object + PagedResponse-Map: + properties: + data: + description: Data contains the actual response payload + items: + $ref: '#/definitions/Map' + type: array + pagination: + allOf: + - $ref: '#/definitions/Pagination' + description: Pagination contains information about paging + type: object + PagedResponse-Rank: + properties: + data: + description: Data contains the actual response payload + items: + $ref: '#/definitions/Rank' + type: array + pagination: + allOf: + - $ref: '#/definitions/Pagination' + description: Pagination contains information about paging + type: object + PagedResponse-Time: + properties: + data: + description: Data contains the actual response payload + items: + $ref: '#/definitions/Time' + type: array + pagination: + allOf: + - $ref: '#/definitions/Pagination' + description: Pagination contains information about paging + type: object + PagedResponse-User: + properties: + data: + description: Data contains the actual response payload + items: + $ref: '#/definitions/User' + type: array + pagination: + allOf: + - $ref: '#/definitions/Pagination' + description: Pagination contains information about paging + type: object + Pagination: + properties: + page: + description: Current page number + type: integer + page_size: + description: Number of items per page + type: integer + total_items: + description: Total number of items across all pages + type: integer + total_pages: + description: Total number of pages + type: integer + type: object + Rank: + properties: + game_id: + type: integer + id: + type: integer + mode_id: + type: integer + rank: + type: number + skill: + type: number + style_id: + type: integer + updated_at: + type: string + user: + $ref: '#/definitions/User' + type: object + Response-Map: + properties: + data: + allOf: + - $ref: '#/definitions/Map' + description: Data contains the actual response payload + type: object + Response-Time: + properties: + data: + allOf: + - $ref: '#/definitions/Time' + description: Data contains the actual response payload + type: object + Response-User: + properties: + data: + allOf: + - $ref: '#/definitions/User' + description: Data contains the actual response payload + type: object + Time: + properties: + date: + type: string + game_id: + type: integer + has_bot: + type: boolean + id: + type: integer + map: + $ref: '#/definitions/Map' + mode_id: + type: integer + style_id: + type: integer + time: + type: integer + user: + $ref: '#/definitions/User' + type: object + User: + properties: + id: + type: integer + muted: + type: boolean + state_id: + type: integer + username: + type: string + type: object +info: + contact: {} + description: |- + Obtain an api key at https://dev.strafes.net + Requires Data:Read permission + title: StrafesNET Data API + version: "1.0" +paths: + /map: + get: + description: Get a list of maps + parameters: + - default: 10 + description: Page size (max 100) + in: query + maximum: 100 + minimum: 1 + name: page_size + type: integer + - default: 1 + description: Page number + in: query + minimum: 1 + name: page_number + type: integer + - in: query + name: game_id + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/PagedResponse-Map' + default: + description: General error response + schema: + $ref: '#/definitions/Error' + security: + - ApiKeyAuth: [] + summary: List maps + tags: + - maps + /map/{id}: + get: + description: Get a specific map by its ID + parameters: + - description: Map ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/Response-Map' + "404": + description: Map not found + schema: + $ref: '#/definitions/Error' + default: + description: General error response + schema: + $ref: '#/definitions/Error' + security: + - ApiKeyAuth: [] + summary: Get map by ID + tags: + - maps + /rank: + get: + description: Get a list of ranks with pagination and filtering + parameters: + - default: 10 + description: Page size (max 100) + in: query + maximum: 100 + minimum: 1 + name: page_size + type: integer + - default: 1 + description: Page number + in: query + minimum: 1 + name: page_number + type: integer + - default: 1 + description: 'Sort by (1: rank asc, 2: skill)' + enum: + - 1 + - 2 + in: query + maximum: 2 + minimum: 1 + name: sort_by + type: integer + - in: query + name: gameId + type: integer + - in: query + name: modeId + type: integer + - in: query + name: styleId + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/PagedResponse-Rank' + default: + description: General error response + schema: + $ref: '#/definitions/Error' + security: + - ApiKeyAuth: [] + summary: List ranks + tags: + - ranks + /time: + get: + description: Get a list of times + parameters: + - default: 10 + description: Page size (max 100) + in: query + maximum: 100 + minimum: 1 + name: page_size + type: integer + - default: 1 + description: Page number + in: query + minimum: 1 + name: page_number + type: integer + - in: query + name: game_id + type: integer + - in: query + name: map_id + type: integer + - in: query + name: mode_id + type: integer + - in: query + name: style_id + type: integer + - in: query + name: user_id + type: integer + - default: "0" + description: Sort field (time ASC, time DESC, date ASC, date DESC) + enum: + - "0" + - "1" + - "2" + - "3" + in: query + name: sort_by + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/PagedResponse-Time' + default: + description: General error response + schema: + $ref: '#/definitions/Error' + security: + - ApiKeyAuth: [] + summary: List times + tags: + - times + /time/{id}: + get: + description: Get a specific time by its ID + parameters: + - description: Time ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/Response-Time' + "404": + description: Time not found + schema: + $ref: '#/definitions/Error' + default: + description: General error response + schema: + $ref: '#/definitions/Error' + security: + - ApiKeyAuth: [] + summary: Get time by ID + tags: + - times + /user: + get: + description: Get a list of users + parameters: + - default: 10 + description: Page size (max 100) + in: query + maximum: 100 + minimum: 1 + name: page_size + type: integer + - default: 1 + description: Page number + in: query + minimum: 1 + name: page_number + type: integer + - in: query + name: state_id + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/PagedResponse-User' + default: + description: General error response + schema: + $ref: '#/definitions/Error' + security: + - ApiKeyAuth: [] + summary: List users + tags: + - users + /user/{id}: + get: + description: Get a specific user by their ID + parameters: + - description: User ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/Response-User' + "404": + description: User not found + schema: + $ref: '#/definitions/Error' + default: + description: General error response + schema: + $ref: '#/definitions/Error' + security: + - ApiKeyAuth: [] + summary: Get user by ID + tags: + - users + /user/{id}/rank: + get: + description: Get a specific rank for a user by their ID + parameters: + - description: User ID + in: path + name: id + required: true + type: integer + - in: query + name: gameId + type: integer + - in: query + name: modeId + type: integer + - in: query + name: styleId + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/Response-User' + "404": + description: User not found + schema: + $ref: '#/definitions/Error' + default: + description: General error response + schema: + $ref: '#/definitions/Error' + security: + - ApiKeyAuth: [] + summary: Get rank by user ID + tags: + - users +securityDefinitions: + ApiKeyAuth: + in: header + name: X-API-Key + type: apiKey +swagger: "2.0"