openapi spec quality audit derived

{
  "input": {
    "body": {
      "specification": {
        "paths": {
          "/widgets": {
            "get": {
              "responses": {
                "200": {}
              }
            },
            "post": {
              "responses": {},
              "parameters": [
                {
                  "name": "dry_run"
                }
              ],
              "operationId": "makeWidget"
            }
          },
          "/widgets/{id}": {
            "get": {
              "summary": "Fetch",
              "security": [
                {
                  "undefinedScheme": []
                }
              ],
              "responses": {
                "200": {
                  "description": "ok"
                }
              },
              "operationId": "makeWidget"
            }
          }
        },
        "openapi": "3.0.3"
      }
    },
    "type": "http",
    "method": "POST",
    "bodyType": "json"
  },
  "output": {
    "type": "json",
    "example": {
      "limits": {
        "maxFindings": 500,
        "maxOperations": 500,
        "maxClientOperations": 200,
        "maxRequestBodyBytes": 262144
      },
      "version": "3.0.3",
      "complete": true,
      "findings": [
        {
          "code": "OPERATION_ID_MISSING",
          "detail": "GET /widgets has no operationId, so a client generator must invent a method name.",
          "operation": "GET /widgets"
        },
        {
          "code": "OPERATION_UNDOCUMENTED",
          "detail": "GET /widgets has neither a summary nor a description.",
          "operation": "GET /widgets"
        },
        {
          "code": "RESPONSE_UNDESCRIBED",
          "detail": "GET /widgets: status 200 carries no description, which OpenAPI requires.",
          "status": "200",
          "operation": "GET /widgets"
        }
      ],
      "request_id": "example-request",
      "service_id": "openapi_spec_quality_audit",
      "assumptions": [
        "The audit is about whether a client or documentation generator can work from this document, not about API design taste.",
        "operationId and descriptions are required by default because a generator needs both; either requirement can be turned off."
      ],
      "limitations": [
        "Structural quality of one document. Whether the API behaves as described is not assessed, and this is not a security or compliance statement.",
        "generation_ready is true only when the document was read in full and nothing a generator needs was missing."
      ],
      "observed_at": "2026-10-02T00:00:00.000Z",
      "not_examined": [],
      "finding_count": 9,
      "operation_count": 3,
      "service_version": "1.0.0",
      "findings_by_code": {
        "NO_RESPONSE_DECLARED": 1,
        "OPERATION_ID_MISSING": 1,
        "RESPONSE_UNDESCRIBED": 1,
        "DUPLICATE_OPERATION_ID": 1,
        "OPERATION_UNDOCUMENTED": 2,
        "PARAMETER_SCHEMA_MISSING": 1,
        "SECURITY_SCHEME_UNDEFINED": 1,
        "PARAMETER_LOCATION_MISSING": 1
      },
      "generation_ready": false,
      "security_scheme_count": 0,
      "component_schema_count": 0,
      "operations_without_description": 2,
      "operations_without_operation_id": 1
    }
  }
}