docs: improve openapi spec

Author: ctron

modules/fundamental/src/advisory/endpoints/mod.rs

@@ -240,7 +240,7 @@ pub async fn upload(
     tag = "advisory",
     operation_id = "downloadAdvisory",
     params(
-        ("key" = Id, Path),
+        ("key" = Id, Path, description = "Identifier of the advisory, either `urn:uuid:<uuid>` or a digest e.g. `sha256:<hex>`"),
     ),
     responses(
         (status = 200, description = "Download a an advisory", body = inline(BinaryData)),

modules/fundamental/src/purl/endpoints/base.rs

@@ -21,7 +21,7 @@ use trustify_common::{
     operation_id = "getBasePurl",
     tag = "purl",
     params(
-        ("key" = String, Path, description = "opaque identifier for a base PURL, or a URL-encoded pURL itself")
+        ("key" = String, Path, description = "opaque identifier for a base PURL, or a URL-encoded full pURL starting with `pkg:` (e.g. `pkg:golang/k8s.io%2Fapiserver`)")
     ),
     responses(
         (status = 200, description = "Details for the versionless base PURL", body = BasePurlDetails),

modules/fundamental/src/sbom/endpoints/mod.rs

@@ -610,7 +610,7 @@ pub async fn upload(
     tag = "sbom",
     operation_id = "downloadSbom",
     params(
-        ("key" = Id, Path),
+        ("key" = Id, Path, description = "Identifier of the SBOM, either `urn:uuid:<uuid>` or a digest e.g. `sha256:<hex>`"),
     ),
     responses(
         (status = 200, description = "Download a an SBOM", body = inline(BinaryData)),

openapi.yaml

@@ -291,6 +291,7 @@ paths:
       parameters:
       - name: key
         in: path
+        description: Identifier of the advisory, either `urn:uuid:<uuid>` or a digest e.g. `sha256:<hex>`
         required: true
         schema:
           $ref: '#/components/schemas/Id'
@@ -2256,7 +2257,7 @@ paths:
       parameters:
       - name: key
         in: path
-        description: opaque identifier for a base PURL, or a URL-encoded pURL itself
+        description: opaque identifier for a base PURL, or a URL-encoded full pURL starting with `pkg:` (e.g. `pkg:golang/k8s.io%2Fapiserver`)
         required: true
         schema:
           type: string
@@ -3132,6 +3133,7 @@ paths:
       parameters:
       - name: key
         in: path
+        description: Identifier of the SBOM, either `urn:uuid:<uuid>` or a digest e.g. `sha256:<hex>`
         required: true
         schema:
           $ref: '#/components/schemas/Id'