API Documentation Generator (from OpenAPI Spec or Plain Description)

{
  "type": "object",
  "anyOf": [
    {
      "required": [
        "openapi_spec"
      ]
    },
    {
      "required": [
        "endpoint_description"
      ]
    }
  ],
  "properties": {
    "openapi_spec": {
      "type": "string",
      "description": "A full OpenAPI/Swagger spec as a JSON string. Provide this OR endpoint_description."
    },
    "endpoint_description": {
      "type": "string",
      "description": "A plain-language description of a single endpoint (method, path, what it does, parameters, auth). Provide this OR openapi_spec."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "markdown": {
      "type": "string",
      "description": "The full generated API documentation in markdown: a description, an authentication section, one subsection per documented endpoint with a parameter table, a request example, a response example, and an error-code table. Observed as a single-endpoint doc on a natural-language input and as a two-endpoint doc (sections separated by '---') on a two-path OpenAPI spec input -- length and section count scale with the number of endpoints described."
    },
    "source_type": {
      "type": "string",
      "description": "Which input field drove generation. Observed as 'natural_language' (endpoint_description was supplied) and 'openapi' (openapi_spec was supplied)."
    },
    "total_endpoints": {
      "type": "number",
      "description": "Equal to endpoints_documented.length on both fixtures observed (1 and 2)."
    },
    "authentication_type": {
      "type": "string",
      "description": "Observed as 'api-key' (natural-language input describing an Authorization header) and 'none' (OpenAPI spec with no security scheme) -- other values are plausible but unconfirmed."
    },
    "endpoints_documented": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "The endpoint's path, e.g. '/users/{id}'."
          },
          "method": {
            "type": "string",
            "description": "HTTP method, e.g. 'GET', 'POST'."
          },
          "summary": {
            "type": "string",
            "description": "One-line summary of what the endpoint does."
          },
          "requires_auth": {
            "type": "boolean"
          },
          "parameters_count": {
            "type": "number",
            "description": "Observed 1 (a path parameter) and 0 (no parameters) across the two fixtures."
          }
        },
        "additionalProperties": true
      },
      "description": "One entry per endpoint the markdown covers. Observed as a single entry for a natural-language endpoint_description input and as two entries (GET and POST on the same path) for a two-path OpenAPI spec input."
    }
  },
  "description": "The generated documentation result, as returned at routing.responseResultPath ($.output).",
  "additionalProperties": true
}