@gv-sh/specgen-server
Version:
SpecGen Server - API for Speculative Fiction Generator
1,674 lines (1,673 loc) • 66.6 kB
JSON
{
"openapi": "3.0.0",
"info": {
"title": "SpecGen API",
"version": "1.0.0",
"description": "API documentation for SpecGen - a speculative fiction generator",
"license": {
"name": "ISC",
"url": "https://opensource.org/licenses/ISC"
}
},
"servers": [
{
"url": "http://localhost:3000",
"description": "Local development server"
}
],
"components": {
"schemas": {
"Category": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the category",
"example": "science-fiction"
},
"name": {
"type": "string",
"description": "Display name of the category",
"example": "Science Fiction"
},
"description": {
"type": "string",
"description": "Optional description of the category",
"example": "Stories set in the future with advanced technology"
},
"visibility": {
"type": "string",
"description": "Whether to show or hide this category in the UI",
"enum": [
"Show",
"Hide"
],
"example": "Show"
},
"year": {
"type": "integer",
"description": "Year associated with this category",
"example": 2050
}
},
"required": [
"id",
"name",
"visibility"
]
},
"Parameter": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the parameter",
"example": "science-fiction-technology-level"
},
"name": {
"type": "string",
"description": "Display name of the parameter",
"example": "Technology Level"
},
"description": {
"type": "string",
"description": "Optional description of the parameter",
"example": "The level of technological advancement in the story"
},
"visibility": {
"type": "string",
"description": "Visibility level of this parameter",
"enum": [
"Basic",
"Advanced"
],
"example": "Basic"
},
"type": {
"type": "string",
"description": "Type of the parameter input",
"enum": [
"Dropdown",
"Slider",
"Toggle Switch",
"Radio Buttons",
"Checkbox"
],
"example": "Dropdown"
},
"categoryId": {
"type": "string",
"description": "ID of the category this parameter belongs to",
"example": "science-fiction"
},
"values": {
"oneOf": [
{
"type": "array",
"description": "For Dropdown, Radio Buttons, and Checkbox types",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "near-future"
},
"label": {
"type": "string",
"example": "Near Future"
}
}
},
"example": [
{
"id": "near-future",
"label": "Near Future"
},
{
"id": "advanced",
"label": "Advanced"
}
]
},
{
"type": "object",
"description": "For Toggle Switch type",
"properties": {
"on": {
"type": "string",
"example": "Yes"
},
"off": {
"type": "string",
"example": "No"
}
},
"example": {
"on": "Yes",
"off": "No"
}
}
]
},
"config": {
"type": "object",
"description": "Configuration for Slider type",
"properties": {
"min": {
"type": "number",
"example": 0
},
"max": {
"type": "number",
"example": 100
},
"step": {
"type": "number",
"example": 1
}
},
"example": {
"min": 0,
"max": 100,
"step": 1
}
}
},
"required": [
"id",
"name",
"type",
"categoryId"
]
},
"Content": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the content",
"example": "content-1648236587000-123"
},
"title": {
"type": "string",
"description": "Title of the generated content",
"example": "Space Explorer Adventure"
},
"type": {
"type": "string",
"description": "Type of content (fiction or image)",
"enum": [
"fiction",
"image"
],
"example": "fiction"
},
"content": {
"type": "string",
"description": "The generated fiction content (only for fiction type)",
"example": "The starship Nebula drifted silently through the endless void of space..."
},
"imageUrl": {
"type": "string",
"description": "URL of the generated image (only for image type)",
"example": "https://example.com/generated-image.jpg"
},
"year": {
"type": "integer",
"description": "Year in which the story is set",
"example": 2085
},
"parameterValues": {
"type": "object",
"description": "Parameters used to generate this content",
"example": {
"science-fiction": {
"science-fiction-technology-level": "Near Future",
"science-fiction-alien-life": true
}
}
},
"metadata": {
"type": "object",
"description": "Additional metadata about the generation",
"example": {
"model": "gpt-4o-mini",
"tokens": 1250
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the content was created",
"example": "2023-04-15T12:34:56.789Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "When the content was last updated",
"example": "2023-04-15T12:34:56.789Z"
}
},
"required": [
"id",
"title",
"type",
"parameterValues",
"createdAt",
"updatedAt"
]
},
"ContentList": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Content"
}
},
"ContentResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/Content"
}
},
"required": [
"success",
"data"
]
},
"ContentListResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/ContentList"
}
},
"required": [
"success",
"data"
]
},
"ContentDeleteResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Content 'Space Explorer Adventure' deleted successfully"
},
"data": {
"type": "object",
"properties": {
"deletedContent": {
"$ref": "#/components/schemas/Content"
}
}
}
},
"required": [
"success",
"message",
"data"
]
},
"GenerationParameters": {
"type": "object",
"description": "Object containing parameterValues object that maps category IDs to parameter selections. The parameterValues object has category IDs as keys, with each value being an object of parameter ID/value pairs.\n",
"properties": {
"parameterValues": {
"type": "object",
"description": "Map of category IDs to parameter selections",
"example": {
"science-fiction": {
"science-fiction-technology-level": "Near Future",
"science-fiction-alien-life": true,
"science-fiction-space-exploration-focus": 7
},
"fantasy": {
"fantasy-magic-system": "Elemental",
"fantasy-mythical-creatures": [
"Dragons",
"Elves"
]
}
}
},
"contentType": {
"type": "string",
"description": "Type of content to generate ('fiction', 'image', or 'combined')",
"enum": [
"fiction",
"image",
"combined"
],
"default": "fiction"
},
"year": {
"type": "integer",
"description": "Year in which the story is set (e.g., 2050, 2100)",
"example": 2085
},
"title": {
"type": "string",
"description": "Optional title to use for the story (if not provided, one will be generated)",
"example": "The Last Frontier"
}
},
"required": [
"parameterValues"
]
},
"GenerationResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether the generation was successful",
"example": true
},
"content": {
"type": "string",
"description": "Generated story content (only provided for fiction or combined type)",
"example": "The starship Nebula drifted silently through the endless void of space..."
},
"imageData": {
"type": "string",
"description": "Base64-encoded image data (only provided for image or combined type)",
"example": "iVBORw0KGgoAAAANSUhEUgAA..."
},
"title": {
"type": "string",
"description": "Title of the generated story (either provided or extracted from content)",
"example": "The Last Frontier"
},
"year": {
"type": "integer",
"description": "Year in which the story is set",
"example": 2085
},
"metadata": {
"type": "object",
"properties": {
"model": {
"type": "string",
"description": "The AI model used for generation (for fiction or image type)",
"example": "gpt-4o-mini"
},
"tokens": {
"type": "integer",
"description": "Total tokens used for this generation (for fiction type)",
"example": 1250
},
"prompt": {
"type": "string",
"description": "Prompt used for image generation (for image type)",
"example": "A futuristic city with flying vehicles..."
},
"fiction": {
"type": "object",
"description": "Fiction generation metadata (for combined type)",
"properties": {
"model": {
"type": "string",
"example": "gpt-4o-mini"
},
"tokens": {
"type": "integer",
"example": 1250
}
}
},
"image": {
"type": "object",
"description": "Image generation metadata (for combined type)",
"properties": {
"model": {
"type": "string",
"example": "dall-e-3"
},
"prompt": {
"type": "string",
"example": "A fantasy landscape with dragons and elves..."
}
}
}
}
}
},
"required": [
"success",
"metadata"
]
},
"GenerationError": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error": {
"type": "string",
"example": "Invalid parameters: Parameter 'param-123456' not found"
}
},
"required": [
"success",
"error"
]
},
"Settings": {
"type": "object",
"properties": {
"ai": {
"type": "object",
"properties": {
"models": {
"type": "object",
"properties": {
"fiction": {
"type": "string",
"description": "AI model for fiction generation",
"example": "gpt-4o-mini"
},
"image": {
"type": "string",
"description": "AI model for image generation",
"example": "dall-e-3"
}
}
},
"parameters": {
"type": "object",
"properties": {
"fiction": {
"type": "object",
"properties": {
"temperature": {
"type": "number",
"description": "Temperature for fiction generation",
"example": 0.8
},
"max_tokens": {
"type": "integer",
"description": "Maximum tokens for fiction generation",
"example": 1000
},
"default_story_length": {
"type": "integer",
"description": "Default story length in words",
"example": 500
}
}
},
"image": {
"type": "object",
"properties": {
"size": {
"type": "string",
"description": "Image size for generation",
"example": "1024x1024"
},
"quality": {
"type": "string",
"description": "Image quality for generation",
"enum": [
"standard",
"hd"
],
"example": "standard"
}
}
}
}
}
}
},
"defaults": {
"type": "object",
"properties": {
"content_type": {
"type": "string",
"description": "Default content type for generation",
"enum": [
"fiction",
"image"
],
"example": "fiction"
}
}
}
}
},
"SettingsResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/Settings"
}
}
},
"SettingsUpdateRequest": {
"type": "object",
"description": "Partial settings update, only include fields to update",
"example": {
"ai": {
"parameters": {
"fiction": {
"temperature": 0.9,
"max_tokens": 1500
}
}
}
}
},
"SettingsResetResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Settings reset to defaults"
},
"data": {
"$ref": "#/components/schemas/Settings"
}
}
}
},
"responses": {
"Error": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error": {
"type": "string",
"example": "Error message details"
}
}
}
}
}
}
}
},
"paths": {
"/api/categories": {
"get": {
"summary": "Get all categories",
"tags": [
"Categories"
],
"responses": {
"200": {
"description": "List of categories",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/Error"
}
}
},
"post": {
"summary": "Create a new category",
"tags": [
"Categories"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "Science Fiction"
},
"description": {
"type": "string",
"example": "Stories set in the future with advanced technology"
},
"visibility": {
"type": "string",
"enum": [
"Show",
"Hide"
],
"default": "Show",
"example": "Show"
}
}
},
"examples": {
"basicCategory": {
"summary": "Basic category with just a name",
"value": {
"name": "Science Fiction"
}
},
"fullCategory": {
"summary": "Complete category with all fields",
"value": {
"name": "Fantasy",
"description": "Stories with magic and mythical creatures",
"visibility": "Show"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Category created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/Category"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/categories/{id}": {
"get": {
"summary": "Get a category by ID",
"tags": [
"Categories"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Category ID",
"example": "science-fiction"
}
],
"responses": {
"200": {
"description": "Category details",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/Category"
}
}
}
}
}
},
"404": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
},
"put": {
"summary": "Update a category",
"tags": [
"Categories"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Category ID",
"example": "science-fiction"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Updated Science Fiction"
},
"description": {
"type": "string",
"example": "Updated description for science fiction category"
},
"visibility": {
"type": "string",
"enum": [
"Show",
"Hide"
],
"example": "Show"
}
}
},
"example": {
"name": "Updated Science Fiction",
"description": "Updated description for science fiction category",
"visibility": "Show"
}
}
}
},
"responses": {
"200": {
"description": "Category updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/Category"
}
}
}
}
}
},
"404": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
},
"delete": {
"summary": "Delete a category and its parameters",
"tags": [
"Categories"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Category ID",
"example": "science-fiction"
}
],
"responses": {
"200": {
"description": "Category deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Category 'Science Fiction' deleted successfully"
},
"data": {
"type": "object",
"properties": {
"deletedCategory": {
"$ref": "#/components/schemas/Category"
},
"deletedParameters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Parameter"
}
},
"parameterCount": {
"type": "integer",
"example": 3
}
}
}
}
}
}
}
},
"404": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/content": {
"get": {
"summary": "Get all generated content",
"description": "Retrieve a list of all generated content, with optional filtering by type or year",
"tags": [
"Content"
],
"parameters": [
{
"in": "query",
"name": "type",
"schema": {
"type": "string",
"enum": [
"fiction",
"image"
]
},
"description": "Filter content by type"
},
{
"in": "query",
"name": "year",
"schema": {
"type": "integer"
},
"description": "Filter content by story year"
}
],
"responses": {
"200": {
"description": "List of generated content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContentListResponse"
}
}
}
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/content/years": {
"get": {
"summary": "Get all years with content",
"description": "Retrieve a list of all years that have generated content",
"tags": [
"Content"
],
"responses": {
"200": {
"description": "List of years with content",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
2050,
2085,
2100,
2150
]
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/content/year/{year}": {
"get": {
"summary": "Get content by year",
"description": "Retrieve all content set in a specific year",
"tags": [
"Content"
],
"parameters": [
{
"in": "path",
"name": "year",
"required": true,
"schema": {
"type": "integer"
},
"description": "Year to filter by"
}
],
"responses": {
"200": {
"description": "List of content for the specified year",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContentListResponse"
}
}
}
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/content/{id}": {
"get": {
"summary": "Get a specific generated content",
"description": "Retrieve a single generated content item by its ID",
"tags": [
"Content"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Content ID"
}
],
"responses": {
"200": {
"description": "Generated content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContentResponse"
}
}
}
},
"404": {
"description": "Content not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/responses/Error"
}
}
}
},
"500": {
"$ref": "#/components/responses/Error"
}
}
},
"put": {
"summary": "Update generated content",
"description": "Update a generated content's title, content, imageUrl, or year",
"tags": [
"Content"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Content ID"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "New title for the content",
"example": "Updated Space Adventure"
},
"content": {
"type": "string",
"description": "New content (for fiction type only)",
"example": "Updated story content..."
},
"imageUrl": {
"type": "string",
"description": "New image URL (for image type only)",
"example": "https://example.com/new-image.jpg"
},
"year": {
"type": "integer",
"description": "New year for the story setting",
"example": 2095
}
}
}
}
}
},
"responses": {
"200": {
"description": "Updated content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContentResponse"
}
}
}
},
"404": {
"description": "Content not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/responses/Error"
}
}
}
},
"500": {
"$ref": "#/components/responses/Error"
}
}
},
"delete": {
"summary": "Delete generated content",
"description": "Delete a generated content item by its ID",
"tags": [
"Content"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Content ID"
}
],
"responses": {
"200": {
"description": "Content deleted successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContentDeleteResponse"
}
}
}
},
"404": {
"description": "Content not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/responses/Error"
}
}
}
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/database/download": {
"get": {
"summary": "Download the database file",
"description": "Retrieve the current database file in JSON format.",
"responses": {
"200": {
"description": "Database data retrieved successfully.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"404": {
"description": "No database data found."
},
"500": {
"description": "Failed to download database."
}
}
}
},
"/api/database/generations/download": {
"get": {
"summary": "Download the generations database",
"description": "Retrieve all generated content from the SQLite database in JSON format.",
"responses": {
"200": {
"description": "Generations data retrieved successfully.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"404": {
"description": "No generations data found."
},
"500": {
"description": "Failed to download generations database."
}
}
}
},
"/api/database/restore": {
"post": {
"summary": "Restore the database from a file",
"description": "Restore the database using an uploaded JSON file. The file should contain valid \"categories\" and \"parameters\" arrays.",
"consumes": [
"multipart/form-data"
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Database restored successfully."
},
"400": {
"description": "No file uploaded, invalid JSON file, or invalid database structure."
},
"500": {
"description": "Failed to restore database."
}
}
}
},
"/api/database/generations/restore": {
"post": {
"summary": "Restore the generations database from a file",
"description": "Restore the generations database using an uploaded JSON file. The file should contain a valid \"generations\" array.",
"consumes": [
"multipart/form-data"
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Generations database restored successfully."
},
"400": {
"description": "No file uploaded, invalid JSON file, or invalid database structure."
},
"500": {
"description": "Failed to restore generations database."
}
}
}
},
"/api/database/reset": {
"post": {
"summary": "Reset the database to an empty state",
"description": "Clear all data from the database by resetting it to an empty state.",
"responses": {
"200": {
"description": "Database reset successfully."
},
"500": {
"description": "Failed to reset database."
}
}
}
},
"/api/database/generations/reset": {
"post": {
"summary": "Reset the generations database to an empty state",
"description": "Clear all data from the generations database by resetting it to an empty state.",
"responses": {
"200": {
"description": "Generations database reset successfully."
},
"500": {
"description": "Failed to reset generations database."
}
}
}
},
"/api/database/reset-all": {
"post": {
"summary": "Reset all databases to an empty state",
"description": "Clear all data from both the primary database and generations database.",
"responses": {
"200": {
"description": "All databases reset successfully."
},
"500": {
"description": "Failed to reset databases."
}
}
}
},
"/api/generate": {
"post": {
"summary": "Generate fiction text or an image based on selected parameters",
"description": "Sends the provided parameter selections to the AI service and returns either a generated story or image URL based on the contentType. The request body must contain a 'parameterValues' object with category IDs as keys, and each category having parameter IDs as keys with their respective values.\n",
"tags": [
"Generation"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"parameterValues"
],
"properties": {
"parameterValues": {
"type": "object",
"description": "Map of category IDs to parameter selections"
},
"contentType": {
"type": "string",
"enum": [
"fiction",
"image",
"combined"
],
"default": "fiction",
"description": "Type of content to generate ('fiction', 'image', or 'combined')"
},
"year": {
"type": "integer",
"description": "Optional year in which to set the story",
"example": 2085
},
"title": {
"type": "string",
"description": "Optional title to use for the story (if not provided, one will be generated)",
"example": "The Last Frontier"
}
}
},
"examples": {
"fictionGeneration": {
"summary": "Fiction generation request",
"value": {
"parameterValues": {
"science-fiction": {
"science-fiction-technology-level": "Near Future",
"science-fiction-alien-life": true,
"science-fiction-space-exploration-focus": 7
}
},
"contentType": "fiction",
"year": 2085
}
},
"imageGeneration": {
"summary": "Image generation request",
"value": {
"parameterValues": {
"fantasy": {
"fantasy-magic-system": "Elemental",
"fantasy-mythical-creatures": [
"Dragons",
"Elves"
]
}
},
"contentType": "image",
"year": 2150
}
},
"combinedGeneration": {
"summary": "Combined fiction and image generation request",
"value": {
"parameterValues": {
"fantasy": {
"fantasy-magic-system": "Elemental",
"fantasy-mythical-creatures": [
"Dragons",
"Elves"
]
}
},
"contentType": "combined",
"year": 2100,
"title": "The Crystal Caves of Eldoria"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Content generated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerationResponse"
}
}
}
},
"400": {
"description": "Invalid parameters provided",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerationError"
}
}
}
},
"500": {
"description": "AI service error or other server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerationError"
}
}
}
}
}
}
},
"/api/health": {
"get": {
"summary": "Get server health status",
"description": "Retrieves system health information and server status",
"tags": [
"Health"
],
"responses": {
"200": {
"description": "Health check successful",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "healthy"
},
"version": {
"type": "string",
"example": "1.0.0"
},
"uptime": {
"type": "number",
"description": "Server uptime in seconds",
"example": 3600
},
"timestamp": {
"type": "string",
"format": "date-time",
"example": "2023-04-25T12:34:56.789Z"
},
"memory": {
"type": "object",
"properties": {
"total": {
"type": "number",
"description": "Total memory in MB",
"example": 8192
},
"free": {
"type": "number",
"description": "Free memory in MB",
"example": 4096
},
"usage": {
"type": "number",
"description": "Memory usage percentage",
"example": 50
}
}
},
"system": {
"type": "object",
"properties": {
"platform": {
"type": "string",
"example": "linux"
},
"arch": {
"type": "string",
"example": "x64"
},
"cpus": {
"type": "number",
"example": 4
}
}
},
"services": {
"type": "object",
"properties": {
"database": {
"type": "string",
"example": "connected"
}
}
}
}
}
}
}
},
"500": {
"description": "Health check failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "unhealthy"
},
"error": {
"type": "string",
"example": "Database connection failed"
}
}
}
}
}
}
}
}
},
"/api/health/ping": {
"get": {
"summary": "Simple ping endpoint",
"description": "Returns a simple response to verify the server is running",
"tags": [
"Health"
],
"responses": {
"200": {
"description": "Successful ping response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "pong"
}
}
}
}
}
}
}
}
},
"/api/parameters": {
"get": {
"summary": "Get all parameters or filter by categoryId",
"tags": [
"Parameters"
],
"parameters": [
{
"in": "query",
"name": "categoryId",
"schema": {
"type": "string"
},
"description": "Optional category ID to filter parameters"
}
],
"responses": {
"200": {
"description": "List of parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Parameter"
}
}
}
}
}
}
},