diff --git a/config/settings.py b/config/settings.py index fca070165..82a55ae9c 100644 --- a/config/settings.py +++ b/config/settings.py @@ -289,6 +289,7 @@ "POSTPROCESSING_HOOKS": [ "drf_spectacular.hooks.postprocess_schema_enums", "osidb.hooks.response_metadata_postprocess_hook", + "osidb.hooks.enum_to_extensible_enum_postprocess_hook", ], "ENUM_NAME_OVERRIDES": { "FlawReferenceType": "osidb.models.flaw.reference.FlawReference.FlawReferenceType", diff --git a/openapi.yml b/openapi.yml index e9bebe330..fb3c3e31e 100644 --- a/openapi.yml +++ b/openapi.yml @@ -198,7 +198,7 @@ paths: properties: data: type: string - enum: + x-extensible-enum: - EMPTY - PARTIAL - COMPLETE @@ -219,7 +219,7 @@ paths: type: string state: type: string - enum: + x-extensible-enum: - PENDING - BLOCKED - READY @@ -692,7 +692,7 @@ paths: name: affectedness schema: type: string - enum: + x-extensible-enum: - '' - AFFECTED - NEW @@ -789,7 +789,7 @@ paths: name: cvss_scores__issuer schema: type: string - enum: + x-extensible-enum: - CISA - CVEORG - NIST @@ -927,7 +927,7 @@ paths: name: flaw__impact schema: type: string - enum: + x-extensible-enum: - '' - CRITICAL - IMPORTANT @@ -977,7 +977,7 @@ paths: name: flaw__source schema: type: string - enum: + x-extensible-enum: - '' - ADOBE - APPLE @@ -1122,7 +1122,7 @@ paths: name: impact schema: type: string - enum: + x-extensible-enum: - '' - CRITICAL - IMPORTANT @@ -1173,7 +1173,7 @@ paths: type: array items: type: string - enum: + x-extensible-enum: - -affectedness - -created_dt - -cvss_scores__comment @@ -1265,7 +1265,7 @@ paths: name: resolution schema: type: string - enum: + x-extensible-enum: - '' - DEFER - DELEGATED @@ -1337,7 +1337,7 @@ paths: name: trackers__type schema: type: string - enum: + x-extensible-enum: - BUGZILLA - JIRA - in: query @@ -1584,7 +1584,7 @@ paths: name: issuer schema: type: string - enum: + x-extensible-enum: - CISA - CVEORG - NIST @@ -2199,7 +2199,7 @@ paths: name: alert_type schema: type: string - enum: + x-extensible-enum: - ERROR - WARNING - in: query @@ -2242,7 +2242,7 @@ paths: name: parent_model schema: type: string - enum: + x-extensible-enum: - affect - affectcvss - flaw @@ -2586,7 +2586,7 @@ paths: name: affects__affectedness schema: type: string - enum: + x-extensible-enum: - '' - AFFECTED - NEW @@ -2639,7 +2639,7 @@ paths: name: affects__impact schema: type: string - enum: + x-extensible-enum: - '' - CRITICAL - IMPORTANT @@ -2657,7 +2657,7 @@ paths: name: affects__resolution schema: type: string - enum: + x-extensible-enum: - '' - DEFER - DELEGATED @@ -2777,7 +2777,7 @@ paths: name: affects__trackers__type schema: type: string - enum: + x-extensible-enum: - BUGZILLA - JIRA - in: query @@ -3034,7 +3034,7 @@ paths: name: cvss_scores__issuer schema: type: string - enum: + x-extensible-enum: - CISA - CVEORG - NIST @@ -3119,7 +3119,7 @@ paths: name: impact schema: type: string - enum: + x-extensible-enum: - '' - CRITICAL - IMPORTANT @@ -3202,7 +3202,7 @@ paths: name: major_incident_state schema: type: string - enum: + x-extensible-enum: - '' - APPROVED - CISA_APPROVED @@ -3219,7 +3219,7 @@ paths: name: nist_cvss_validation schema: type: string - enum: + x-extensible-enum: - '' - APPROVED - REJECTED @@ -3236,7 +3236,7 @@ paths: type: array items: type: string - enum: + x-extensible-enum: - -acknowledgments__affiliation - -acknowledgments__created_dt - -acknowledgments__from_upstream @@ -3426,7 +3426,7 @@ paths: name: references__type schema: type: string - enum: + x-extensible-enum: - ARTICLE - EXTERNAL - SOURCE @@ -3524,7 +3524,7 @@ paths: name: requires_cve_description schema: type: string - enum: + x-extensible-enum: - '' - APPROVED - REJECTED @@ -3537,7 +3537,7 @@ paths: name: source schema: type: string - enum: + x-extensible-enum: - '' - ADOBE - APPLE @@ -3709,7 +3709,7 @@ paths: type: array items: type: string - enum: + x-extensible-enum: - '' - DONE - NEW @@ -4445,7 +4445,7 @@ paths: name: issuer schema: type: string - enum: + x-extensible-enum: - CISA - CVEORG - NIST @@ -5454,7 +5454,7 @@ paths: name: type schema: type: string - enum: + x-extensible-enum: - ARTICLE - EXTERNAL - SOURCE @@ -6057,14 +6057,14 @@ paths: name: format schema: type: string - enum: + x-extensible-enum: - json - yaml - in: query name: lang schema: type: string - enum: + x-extensible-enum: - af - ar - ar-dz @@ -6240,7 +6240,7 @@ paths: name: affects__affectedness schema: type: string - enum: + x-extensible-enum: - '' - AFFECTED - NEW @@ -6354,7 +6354,7 @@ paths: name: affects__flaw__impact schema: type: string - enum: + x-extensible-enum: - '' - CRITICAL - IMPORTANT @@ -6404,7 +6404,7 @@ paths: name: affects__flaw__source schema: type: string - enum: + x-extensible-enum: - '' - ADOBE - APPLE @@ -6549,7 +6549,7 @@ paths: name: affects__impact schema: type: string - enum: + x-extensible-enum: - '' - CRITICAL - IMPORTANT @@ -6567,7 +6567,7 @@ paths: name: affects__resolution schema: type: string - enum: + x-extensible-enum: - '' - DEFER - DELEGATED @@ -6716,7 +6716,7 @@ paths: type: array items: type: string - enum: + x-extensible-enum: - -affects__affectedness - -affects__created_dt - -affects__embargoed @@ -6796,7 +6796,7 @@ paths: name: type schema: type: string - enum: + x-extensible-enum: - BUGZILLA - JIRA - in: query @@ -7120,7 +7120,7 @@ paths: name: issuer schema: type: string - enum: + x-extensible-enum: - CISA - CVEORG - NIST @@ -8101,11 +8101,11 @@ components: - ps_module - updated_dt AffectednessEnum: - enum: + type: string + x-extensible-enum: - NEW - AFFECTED - NOTAFFECTED - type: string Alert: type: object description: Alerts indicate some inconsistency in a linked flaw, affect, tracker @@ -8138,10 +8138,10 @@ components: - parent_uuid - uuid AlertTypeEnum: - enum: + type: string + x-extensible-enum: - WARNING - ERROR - type: string Audit: type: object properties: @@ -8211,7 +8211,7 @@ components: - pgh_obj_model - pgh_slug BlankEnum: - enum: + x-extensible-enum: - '' Comment: type: object @@ -8285,11 +8285,11 @@ components: - text - updated_dt CvssVersionEnum: - enum: + type: string + x-extensible-enum: - V2 - V3 - V4 - type: string EPSS: type: object properties: @@ -8361,11 +8361,11 @@ components: - maturity_preliminary - source ExploitOnlyReportDataSourceEnum: - enum: + type: string + x-extensible-enum: - CISA - Metasploit - Exploit-DB - type: string Flaw: type: object description: serialize flaw model @@ -8488,7 +8488,7 @@ components: type: string state: type: string - enum: + x-extensible-enum: - '' - NEW - TRIAGE @@ -9358,12 +9358,12 @@ components: - updated_dt - url FlawReferenceType: - enum: + type: string + x-extensible-enum: - ARTICLE - EXTERNAL - SOURCE - UPSTREAM - type: string FlawReportData: type: object properties: @@ -9488,22 +9488,23 @@ components: required: - version ImpactEnum: - enum: + type: string + x-extensible-enum: - LOW - MODERATE - IMPORTANT - CRITICAL - type: string IssuerEnum: - enum: + type: string + x-extensible-enum: - CVEORG - RH - NIST - OSV - CISA - type: string MajorIncidentStateEnum: - enum: + type: string + x-extensible-enum: - REQUESTED - REJECTED - APPROVED @@ -9511,14 +9512,13 @@ components: - MINOR - ZERO_DAY - INVALID - type: string MaturityPreliminaryEnum: - enum: + type: integer + x-extensible-enum: - 0 - 1 - 2 - 3 - type: integer ModuleComponent: type: object properties: @@ -9541,19 +9541,19 @@ components: - selected - streams NistCvssValidationEnum: - enum: + type: string + x-extensible-enum: - REQUESTED - APPROVED - REJECTED - type: string NotAffectedJustificationEnum: - enum: + type: string + x-extensible-enum: - Component not Present - Inline Mitigations already Exist - Vulnerable Code cannot be Controlled by Adversary - Vulnerable Code not in Execute Path - Vulnerable Code not Present - type: string Package: type: object description: package_versions (Package model) serializer for read-only use in @@ -10063,22 +10063,23 @@ components: required: - reason RequiresCveDescriptionEnum: - enum: + type: string + x-extensible-enum: - REQUESTED - APPROVED - REJECTED - type: string ResolutionEnum: - enum: + type: string + x-extensible-enum: - FIX - DEFER - WONTFIX - OOSS - DELEGATED - WONTREPORT - type: string SourceBe0Enum: - enum: + type: string + x-extensible-enum: - ADOBE - APPLE - ASF @@ -10168,21 +10169,20 @@ components: - XCHAT - XEN - XPDF - type: string SpecialHandlingEnum: - enum: + type: string + x-extensible-enum: - Major Incident - KEV (active exploit case) - compliance-priority - contract-priority - type: string StateEnum: - enum: + type: string + x-extensible-enum: - NEW - REQ - SKIP - DONE - type: string SupportedProducts: type: object properties: @@ -10500,10 +10500,10 @@ components: - modules_components - not_applicable TrackerType: - enum: + type: string + x-extensible-enum: - JIRA - BUGZILLA - type: string securitySchemes: KerberosAuthentication: type: http diff --git a/osidb/hooks.py b/osidb/hooks.py index 871235f3d..634578f2e 100644 --- a/osidb/hooks.py +++ b/osidb/hooks.py @@ -75,3 +75,31 @@ def response_metadata_postprocess_hook(result, generator, **kwargs): del response["description"] response["description"] = "" return result + + +def _enum_to_extensible_enum(element): + """ + Given an element with `enum` keyword, replace it with `x-extensible-enum`. + """ + if isinstance(element, dict): + if "enum" in element and isinstance(element["enum"], list): + element["x-extensible-enum"] = element.pop("enum") + for key in element.keys(): + _enum_to_extensible_enum(element[key]) + elif isinstance(element, list): + for item in element: + _enum_to_extensible_enum(item) + + +def enum_to_extensible_enum_postprocess_hook(result, generator, **kwargs): + """ + drf-spectacular postprocessing hook for changing `enum` to `x-extensible-enum`. + + `x-extensible-enum` is a relatively well-known proprietary extension of + the OpenAPI schema used by the Zalando API Guidelines (#112), we use it to + tell clients that any enums in OSIDB should be treated as a continuously list + of growing values and that any additions are **not** considered a breaking + change. + """ + _enum_to_extensible_enum(result) + return result