[pkgsite] internal/api: extract comments as descriptions for OpenAPI schemas

1 view
Skip to first unread message

Hyang-Ah Hana Kim (Gerrit)

unread,
May 9, 2026, 8:45:05 PM (2 days ago) May 9
to goph...@pubsubhelper.golang.org, Hyang-Ah Hana Kim, golang-co...@googlegroups.com

Hyang-Ah Hana Kim has uploaded the change for review

Commit message

internal/api: extract comments as descriptions for OpenAPI schemas

Update generateSchemas in openapi_test.go to extract field doc
or comment and use it as the description in the generated OpenAPI schema.
Also update openapi.yaml with the regenerated spec.
Change-Id: Ic3c64701315fcc18bfdcf86bdd978253a905e653

Change diff

diff --git a/internal/api/openapi.yaml b/internal/api/openapi.yaml
index 12b7f88..d5a5b5c 100644
--- a/internal/api/openapi.yaml
+++ b/internal/api/openapi.yaml
@@ -506,12 +506,15 @@
             "type": "array"
           },
           "code": {
+            "description": "HTTP status code",
             "type": "integer"
           },
           "err": {
-            "$ref": "#/components/schemas/error"
+            "$ref": "#/components/schemas/error",
+            "description": "Unexported field for internal tracking"
           },
           "fixes": {
+            "description": "suggestions for how to fix",
             "items": {
               "type": "string"
             },
@@ -543,6 +546,7 @@
       "Module": {
         "properties": {
           "commitTime": {
+            "description": "CommitTime is the timestamp returned by the module proxy's .info endpoint,\nrepresenting the time the version was created.",
             "format": "date-time",
             "type": "string"
           },
@@ -595,12 +599,15 @@
             "type": "string"
           },
           "hasGoMod": {
+            "description": "module has go.mod file?",
             "type": "boolean"
           },
           "isRedistributable": {
+            "description": "license allows distribution?",
             "type": "boolean"
           },
           "latestVersion": {
+            "description": "latest unretracted version",
             "type": "string"
           },
           "modulePath": {
@@ -673,6 +680,7 @@
       "PackageInfo": {
         "properties": {
           "isRedistributable": {
+            "description": "license allows distribution?",
             "type": "boolean"
           },
           "name": {
diff --git a/internal/api/openapi_test.go b/internal/api/openapi_test.go
index 0e33a12..e8a58ae 100644
--- a/internal/api/openapi_test.go
+++ b/internal/api/openapi_test.go
@@ -345,7 +345,13 @@
 				}
 
 				typeStr := typeExprToString(field.Type)
-				properties[jsonName] = mapFieldType(typeStr)
+				prop := mapFieldType(typeStr)
+				if field.Doc != nil {
+					prop["description"] = strings.TrimSpace(field.Doc.Text())
+				} else if field.Comment != nil {
+					prop["description"] = strings.TrimSpace(field.Comment.Text())
+				}
+				properties[jsonName] = prop
 			}
 
 			schemas[typeName] = map[string]any{

Change information

Files:
  • M internal/api/openapi.yaml
  • M internal/api/openapi_test.go
Change size: S
Delta: 2 files changed, 16 insertions(+), 2 deletions(-)
Open in Gerrit

Related details

Attention set is empty
Submit Requirements:
  • requirement is not satisfiedCode-Review
  • requirement satisfiedNo-Unresolved-Comments
  • requirement is not satisfiedReview-Enforcement
  • requirement is not satisfiedTryBots-Pass
  • requirement is not satisfiedkokoro-CI-Passes
Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. DiffyGerrit
Gerrit-MessageType: newchange
Gerrit-Project: pkgsite
Gerrit-Branch: master
Gerrit-Change-Id: Ic3c64701315fcc18bfdcf86bdd978253a905e653
Gerrit-Change-Number: 776420
Gerrit-PatchSet: 1
Gerrit-Owner: Hyang-Ah Hana Kim <hya...@gmail.com>
Gerrit-Reviewer: Hyang-Ah Hana Kim <hya...@gmail.com>
unsatisfied_requirement
satisfied_requirement
open
diffy

kokoro (Gerrit)

unread,
May 9, 2026, 9:10:52 PM (2 days ago) May 9
to Hyang-Ah Hana Kim, goph...@pubsubhelper.golang.org, golang...@luci-project-accounts.iam.gserviceaccount.com, golang-co...@googlegroups.com
Attention needed from Hyang-Ah Hana Kim

kokoro voted kokoro-CI+1

Kokoro presubmit build finished with status: SUCCESS
Logs at: https://source.cloud.google.com/results/invocations/64796352-3c93-4a1e-9239-f9dc87ff3930

kokoro-CI+1
Open in Gerrit

Related details

Attention is currently required from:
  • Hyang-Ah Hana Kim
Submit Requirements:
    • requirement is not satisfiedCode-Review
    • requirement satisfiedNo-Unresolved-Comments
    • requirement is not satisfiedReview-Enforcement
    • requirement satisfiedTryBots-Pass
    • requirement satisfiedkokoro-CI-Passes
    Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. DiffyGerrit
    Gerrit-MessageType: comment
    Gerrit-Project: pkgsite
    Gerrit-Branch: master
    Gerrit-Change-Id: Ic3c64701315fcc18bfdcf86bdd978253a905e653
    Gerrit-Change-Number: 776420
    Gerrit-PatchSet: 1
    Gerrit-Owner: Hyang-Ah Hana Kim <hya...@gmail.com>
    Gerrit-Reviewer: Hyang-Ah Hana Kim <hya...@gmail.com>
    Gerrit-Reviewer: kokoro <noreply...@google.com>
    Gerrit-CC: kokoro <noreply...@google.com>
    Gerrit-Attention: Hyang-Ah Hana Kim <hya...@gmail.com>
    Gerrit-Comment-Date: Sun, 10 May 2026 01:10:48 +0000
    Gerrit-HasComments: No
    Gerrit-Has-Labels: Yes
    unsatisfied_requirement
    satisfied_requirement
    open
    diffy

    Ethan Lee (Gerrit)

    unread,
    6:14 PM (5 hours ago) 6:14 PM
    to Hyang-Ah Hana Kim, goph...@pubsubhelper.golang.org, Jonathan Amsterdam, kokoro, golang...@luci-project-accounts.iam.gserviceaccount.com, golang-co...@googlegroups.com
    Attention needed from Hyang-Ah Hana Kim and Jonathan Amsterdam

    Ethan Lee voted and added 2 comments

    Votes added by Ethan Lee

    Code-Review+2

    2 comments

    Patchset-level comments
    File-level comment, Patchset 1 (Latest):
    Ethan Lee . resolved

    Thanks, this is a nice addition!

    File internal/api/openapi.yaml
    Line 602, Patchset 1 (Latest): "description": "module has go.mod file?",
    Ethan Lee . unresolved

    small nit (we can have a TODO for clean up after): I think we should change these comments to be declarative rather than interrogative, given that they are descriptive.

    So maybe in the comment should be "Whether the module has a go.mod file."

    Open in Gerrit

    Related details

    Attention is currently required from:
    • Hyang-Ah Hana Kim
    • Jonathan Amsterdam
    Submit Requirements:
    • requirement satisfiedCode-Review
    • requirement is not satisfiedNo-Unresolved-Comments
    • requirement satisfiedReview-Enforcement
    • requirement satisfiedTryBots-Pass
    • requirement satisfiedkokoro-CI-Passes
    Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. DiffyGerrit
    Gerrit-MessageType: comment
    Gerrit-Project: pkgsite
    Gerrit-Branch: master
    Gerrit-Change-Id: Ic3c64701315fcc18bfdcf86bdd978253a905e653
    Gerrit-Change-Number: 776420
    Gerrit-PatchSet: 1
    Gerrit-Owner: Hyang-Ah Hana Kim <hya...@gmail.com>
    Gerrit-Reviewer: Ethan Lee <etha...@google.com>
    Gerrit-Reviewer: Hyang-Ah Hana Kim <hya...@gmail.com>
    Gerrit-Reviewer: Jonathan Amsterdam <j...@google.com>
    Gerrit-Attention: Jonathan Amsterdam <j...@google.com>
    Gerrit-Comment-Date: Mon, 11 May 2026 22:14:40 +0000
    Gerrit-HasComments: Yes
    Gerrit-Has-Labels: Yes
    satisfied_requirement
    unsatisfied_requirement
    open
    diffy
    Reply all
    Reply to author
    Forward
    0 new messages