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
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/776420
LUCI-TryBot-Result: golang-scoped@luci-project-accounts.iam.gserviceaccount.com <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
kokoro-CI: kokoro <noreply+kokoro@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Ethan Lee <ethanalee@google.com>

cmd/internal/pkgsite-cli/client/types_gen.go

diff --git a/cmd/internal/pkgsite-cli/client/types_gen.go b/cmd/internal/pkgsite-cli/client/types_gen.go
index 0c12147..e963e3a 100644
--- a/cmd/internal/pkgsite-cli/client/types_gen.go
+++ b/cmd/internal/pkgsite-cli/client/types_gen.go
@@ -28,7 +28,7 @@
 	Path              string `json:"path"`
 	Name              string `json:"name"`
 	Synopsis          string `json:"synopsis"`
-	IsRedistributable bool   `json:"isRedistributable"` // license allows distribution?
+	IsRedistributable bool   `json:"isRedistributable"` // Whether the license allows distribution.
 }
 
 type PackagesResponse struct {
@@ -64,8 +64,8 @@
 	ModulePath        string    `json:"modulePath"`
 	Version           string    `json:"version"`
 	CommitTime        time.Time `json:"commitTime"`
-	IsRedistributable bool      `json:"isRedistributable"` // license allows distribution?
-	HasGoMod          bool      `json:"hasGoMod"`          // module has go.mod file?
+	IsRedistributable bool      `json:"isRedistributable"` // Whether the license allows distribution.
+	HasGoMod          bool      `json:"hasGoMod"`          // Whether the module has a go.mod file.
 	LatestVersion     string    `json:"latestVersion"`     // latest unretracted version
 	Deprecated        bool      `json:"deprecated"`
 	DeprecationReason string    `json:"deprecationReason"`

internal/api/openapi.yaml

diff --git a/internal/api/openapi.yaml b/internal/api/openapi.yaml
index 77ccfff..c9f07b1 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": "Whether the module has a go.mod file.",
             "type": "boolean"
           },
           "isRedistributable": {
+            "description": "Whether the license allows distribution.",
             "type": "boolean"
           },
           "latestVersion": {
+            "description": "latest unretracted version",
             "type": "string"
           },
           "modulePath": {
@@ -673,6 +680,7 @@
       "PackageInfo": {
         "properties": {
           "isRedistributable": {
+            "description": "Whether the license allows distribution.",
             "type": "boolean"
           },
           "name": {

internal/api/openapi_test.go

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{

internal/api/types.go

diff --git a/internal/api/types.go b/internal/api/types.go
index 899f528..5d4ae9a 100644
--- a/internal/api/types.go
+++ b/internal/api/types.go
@@ -29,7 +29,7 @@
 	Path              string `json:"path"`
 	Name              string `json:"name"`
 	Synopsis          string `json:"synopsis"`
-	IsRedistributable bool   `json:"isRedistributable"` // license allows distribution?
+	IsRedistributable bool   `json:"isRedistributable"` // Whether the license allows distribution.
 }
 
 type PackagesResponse struct {
@@ -65,8 +65,8 @@
 	ModulePath        string    `json:"modulePath"`
 	Version           string    `json:"version"`
 	CommitTime        time.Time `json:"commitTime"`
-	IsRedistributable bool      `json:"isRedistributable"` // license allows distribution?
-	HasGoMod          bool      `json:"hasGoMod"`          // module has go.mod file?
+	IsRedistributable bool      `json:"isRedistributable"` // Whether the license allows distribution.
+	HasGoMod          bool      `json:"hasGoMod"`          // Whether the module has a go.mod file.
 	LatestVersion     string    `json:"latestVersion"`     // latest unretracted version
 	Deprecated        bool      `json:"deprecated"`
 	DeprecationReason string    `json:"deprecationReason"`