Add proper Godoc comment for properties marked as deprecated (#976)

papkos · web-flow · commit afac8ae432f6 · 2023-03-14T09:14:26.000-07:00
* Add proper Godoc comment for properties marked as deprecated

Also allow to specify a reason for deprecation using an extension: x-deprecated-reason

* Add proper Godoc comment for properties marked as deprecated (fix description)
diff --git a/internal/test/schemas/schemas.gen.go b/internal/test/schemas/schemas.gen.go
diff --git a/internal/test/schemas/schemas.yaml b/internal/test/schemas/schemas.yaml
@@ -121,6 +121,19 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/EnumInObjInArray"
+  /issues/975:
+    get:
+      operationId: Issue975
+      description: |
+        Deprecated fields should get a proper comment
+      responses:
+        200:
+          description: A struct with deprecated fields with varying level of documentation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeprecatedProperty"
+
 components:
   schemas:
     GenericObject:
@@ -165,6 +178,32 @@ components:
             enum:
               - first
               - second
+    DeprecatedProperty:
+      type: object
+      required:
+        - newProp
+        - oldProp
+      properties:
+        newProp:
+          type: string
+          description: Use this now!
+        oldProp1:
+          type: string
+          deprecated: true
+          # description: No description on this one to test generation in that case
+        oldProp2:
+          type: string
+          deprecated: true
+          description: It used to do this and that
+        oldProp3:
+          type: string
+          deprecated: true
+          x-deprecated-reason: Use NewProp instead!
+        oldProp4:
+          type: string
+          deprecated: true
+          x-deprecated-reason: Use NewProp instead!
+          description: It used to do this and that
   parameters:
     StringInPath:
       name: str
@@ -183,4 +222,3 @@ components:
         JWT-format access token.
 security:
   - access-token: [ ]
-
diff --git a/pkg/codegen/extension.go b/pkg/codegen/extension.go
@@ -12,12 +12,13 @@ const (
 	// extGoName is used to override a field name
 	extGoName = "x-go-name"
 	// extGoTypeName is used to override a generated typename for something.
-	extGoTypeName       = "x-go-type-name"
-	extPropGoJsonIgnore = "x-go-json-ignore"
-	extPropOmitEmpty    = "x-omitempty"
-	extPropExtraTags    = "x-oapi-codegen-extra-tags"
-	extEnumVarNames     = "x-enum-varnames"
-	extEnumNames        = "x-enumNames"
+	extGoTypeName        = "x-go-type-name"
+	extPropGoJsonIgnore  = "x-go-json-ignore"
+	extPropOmitEmpty     = "x-omitempty"
+	extPropExtraTags     = "x-oapi-codegen-extra-tags"
+	extEnumVarNames      = "x-enum-varnames"
+	extEnumNames         = "x-enumNames"
+	extDeprecationReason = "x-deprecated-reason"
 )
 
 func extString(extPropValue interface{}) (string, error) {
@@ -82,3 +83,7 @@ func extParseEnumVarNames(extPropValue interface{}) ([]string, error) {
 	}
 	return names, nil
 }
+
+func extParseDeprecationReason(extPropValue interface{}) (string, error) {
+	return extString(extPropValue)
+}
diff --git a/pkg/codegen/schema.go b/pkg/codegen/schema.go
@@ -85,6 +85,7 @@ type Property struct {
 	WriteOnly     bool
 	NeedsFormTag  bool
 	Extensions    map[string]interface{}
+	Deprecated    bool
 }
 
 func (p Property) GoFieldName() string {
@@ -388,6 +389,7 @@ func GenerateGoSchema(sref *openapi3.SchemaRef, path []string) (Schema, error) {
 					ReadOnly:      p.Value.ReadOnly,
 					WriteOnly:     p.Value.WriteOnly,
 					Extensions:    p.Value.Extensions,
+					Deprecated:    p.Value.Deprecated,
 				}
 				outSchema.Properties = append(outSchema.Properties, prop)
 			}
@@ -622,6 +624,18 @@ func GenFieldsFromProperties(props []Property) []string {
 			field += fmt.Sprintf("%s\n", StringWithTypeNameToGoComment(p.Description, p.GoFieldName()))
 		}
 
+		if p.Deprecated {
+			// This comment has to be on its own line for godoc & IDEs to pick up
+			var deprecationReason string
+			if _, ok := p.Extensions[extDeprecationReason]; ok {
+				if extOmitEmpty, err := extParseDeprecationReason(p.Extensions[extDeprecationReason]); err == nil {
+					deprecationReason = extOmitEmpty
+				}
+			}
+
+			field += fmt.Sprintf("%s\n", DeprecationComment(deprecationReason))
+		}
+
 		field += fmt.Sprintf("    %s %s", goFieldName, p.GoTypeDef())
 
 		// Support x-omitempty
diff --git a/pkg/codegen/utils.go b/pkg/codegen/utils.go
@@ -694,6 +694,15 @@ func StringWithTypeNameToGoComment(in, typeName string) string {
 	return stringToGoCommentWithPrefix(in, typeName)
 }
 
+func DeprecationComment(reason string) string {
+	var content = "Deprecated:" // The colon is required at the end even without reason
+	if reason != "" {
+		content += fmt.Sprintf(" %s", reason)
+	}
+
+	return stringToGoCommentWithPrefix(content, "")
+}
+
 func stringToGoCommentWithPrefix(in, prefix string) string {
 	if len(in) == 0 || len(strings.TrimSpace(in)) == 0 { // ignore empty comment
 		return ""
