{
  "openapi": "3.1.0",
  "info": {
    "title": "STL Viewer Render API",
    "version": "1.0.0",
    "description": "Temporarily process an ASCII or binary STL model and render one orthographic view as PNG or all six views as a ZIP archive. Uploaded files are not retained."
  },
  "servers": [
    {
      "url": "/",
      "description": "Current STL Viewer server"
    }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "/api"
  },
  "paths": {
    "/api/render": {
      "post": {
        "operationId": "renderSTL",
        "summary": "Render an STL model",
        "description": "Temporarily processes the uploaded STL and renders the requested view without retaining the file. A single view returns image/png. The all view returns application/zip containing front.png, back.png, left.png, right.png, top.png, and bottom.png.",
        "parameters": [
          {
            "name": "view",
            "in": "query",
            "description": "Camera view to render. Use all to receive all six views in a ZIP archive.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["front", "back", "left", "right", "top", "bottom", "all"],
              "default": "front"
            }
          },
          {
            "name": "width",
            "in": "query",
            "description": "Output image width in pixels.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 128,
              "maximum": 2048,
              "default": 1024
            }
          },
          {
            "name": "height",
            "in": "query",
            "description": "Output image height in pixels.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 128,
              "maximum": 2048,
              "default": 768
            }
          },
          {
            "name": "color",
            "in": "query",
            "description": "Model color as six hexadecimal digits, with or without a leading #. URL-encode # as %23.",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^#?[0-9A-Fa-f]{6}$",
              "default": "4fb3ff"
            }
          },
          {
            "name": "background",
            "in": "query",
            "description": "Background color as six hexadecimal digits, with or without a leading #. URL-encode # as %23.",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^#?[0-9A-Fa-f]{6}$",
              "default": "161a20"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "An ASCII or binary STL file. The filename must end in .stl.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "STL model file"
                  }
                }
              },
              "encoding": {
                "file": {
                  "contentType": "model/stl, application/sla, application/octet-stream"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rendered PNG for one view, or a ZIP archive when view=all.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested output filename.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message"
          }
        },
        "examples": [
          {
            "error": "The uploaded file is not a valid ASCII or binary STL."
          }
        ]
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Missing multipart data, invalid query parameter, or missing file field.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "The endpoint only accepts POST.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UnsupportedMediaType": {
        "description": "The uploaded filename does not end in .stl.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UnprocessableEntity": {
        "description": "The STL could not be parsed or rendered.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InternalServerError": {
            "description": "Rendering failed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "Both render workers are busy.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}