feat: generate @Deprecated annotations for spec-level deprecation (Java/Spring/Docs)

boat-scaffold/src/main/java/com/backbase/oss/codegen/doc/BoatDocsGenerator.java

@@ -1,9 +1,13 @@
 package com.backbase.oss.codegen.doc;
 
+import com.backbase.oss.codegen.utils.DeprecationExtensions;
+import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.Operation;
 import io.swagger.v3.oas.models.servers.Server;
+import java.time.LocalDate;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import lombok.extern.slf4j.Slf4j;
 import org.openapitools.codegen.CliOption;
 import org.openapitools.codegen.CodegenConstants;
@@ -30,6 +34,16 @@ public BoatDocsGenerator() {
         typeAliases = new HashMap<>();
     }
 
+    @Override
+    public void preprocessOpenAPI(OpenAPI openAPI) {
+        super.preprocessOpenAPI(openAPI);
+        boolean specDeprecated = DeprecationExtensions.isSpecDeprecated(openAPI.getInfo());
+        Optional<LocalDate> sunsetDate = DeprecationExtensions.getSunsetDate(openAPI.getInfo());
+        additionalProperties.put("boatApiDeprecated", specDeprecated);
+        additionalProperties.put("boatApiDeprecationMessage",
+            DeprecationExtensions.buildDeprecationMessage(sunsetDate));
+    }
+
     @Override
     public CodegenOperation fromOperation(String path, String httpMethod, Operation operation, List<Server> servers) {
         CodegenOperation codegenOperation = super.fromOperation(path, httpMethod, operation, servers);
@@ -51,9 +65,21 @@ public CodegenOperation fromOperation(String path, String httpMethod, Operation
             }
         }
 
+        applyDeprecationIfNeeded(codegenOperation);
         return codegenOperation;
     }
 
+    private void applyDeprecationIfNeeded(CodegenOperation codegenOperation) {
+        Boolean specDeprecated = (Boolean) additionalProperties.get("boatApiDeprecated");
+        if (specDeprecated != null && specDeprecated) {
+            codegenOperation.isDeprecated = true;
+            String message = (String) additionalProperties.get("boatApiDeprecationMessage");
+            if (message != null && !codegenOperation.vendorExtensions.containsKey(DeprecationExtensions.X_BOAT_DEPRECATION_MESSAGE)) {
+                codegenOperation.vendorExtensions.put(DeprecationExtensions.X_BOAT_DEPRECATION_MESSAGE, message);
+            }
+        }
+    }
+
     @Override
     public String getName() {
         return NAME;

boat-scaffold/src/main/java/com/backbase/oss/codegen/java/BoatCodeGenUtils.java

@@ -1,5 +1,6 @@
 package com.backbase.oss.codegen.java;
 
+import com.backbase.oss.codegen.utils.DeprecationExtensions;
 import io.swagger.v3.oas.models.media.Schema;
 import java.util.Locale;
 import java.util.Map;
@@ -8,7 +9,11 @@
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 import lombok.RequiredArgsConstructor;
+import org.openapitools.codegen.CodegenModel;
+import org.openapitools.codegen.CodegenOperation;
 import org.openapitools.codegen.CodegenProperty;
+import org.openapitools.codegen.model.ModelMap;
+import org.openapitools.codegen.model.ModelsMap;
 import org.openapitools.codegen.utils.ModelUtils;
 
 @NoArgsConstructor(access = AccessLevel.PRIVATE)
@@ -36,6 +41,44 @@
             : null;
     }
 
+    public static void applyDeprecationIfNeeded(CodegenOperation codegenOperation, Map<String, Object> additionalProperties) {
+        Boolean specDeprecated = (Boolean) additionalProperties.get("boatApiDeprecated");
+        if (specDeprecated != null && specDeprecated) {
+            codegenOperation.isDeprecated = true;
+            String message = (String) additionalProperties.get("boatApiDeprecationMessage");
+            if (message != null && !codegenOperation.vendorExtensions.containsKey(DeprecationExtensions.X_BOAT_DEPRECATION_MESSAGE)) {
+                codegenOperation.vendorExtensions.put(DeprecationExtensions.X_BOAT_DEPRECATION_MESSAGE, message);
+            }
+        }
+    }
+
+    public static void applyDeprecationToPropertyIfNeeded(CodegenProperty property, Map<String, Object> additionalProperties) {
+        Boolean specDeprecated = (Boolean) additionalProperties.get("boatApiDeprecated");
+        if (specDeprecated != null && specDeprecated) {
+            property.deprecated = true;
+            String message = (String) additionalProperties.get("boatApiDeprecationMessage");
+            if (message != null && !property.vendorExtensions.containsKey(DeprecationExtensions.X_BOAT_DEPRECATION_MESSAGE)) {
+                property.vendorExtensions.put(DeprecationExtensions.X_BOAT_DEPRECATION_MESSAGE, message);
+            }
+        }
+    }
+
+    public static void applyDeprecationToAllModelsIfNeeded(Map<String, ModelsMap> objs, Map<String, Object> additionalProperties) {
+        Boolean specDeprecated = (Boolean) additionalProperties.get("boatApiDeprecated");
+        if (specDeprecated != null && specDeprecated) {
+            String message = (String) additionalProperties.get("boatApiDeprecationMessage");
+            for (ModelsMap modelsMap : objs.values()) {
+                for (ModelMap modelMap : modelsMap.getModels()) {
+                    CodegenModel model = modelMap.getModel();
+                    model.isDeprecated = true;
+                    if (message != null && !model.vendorExtensions.containsKey(DeprecationExtensions.X_BOAT_DEPRECATION_MESSAGE)) {
+                        model.vendorExtensions.put(DeprecationExtensions.X_BOAT_DEPRECATION_MESSAGE, message);
+                    }
+                }
+            }
+        }
+    }
+
     @RequiredArgsConstructor(staticName = "of")
     @Getter
     static class CodegenValueType {

boat-scaffold/src/main/java/com/backbase/oss/codegen/java/BoatJavaCodeGen.java

@@ -1,16 +1,22 @@
 package com.backbase.oss.codegen.java;
 
 import com.backbase.oss.codegen.java.BoatCodeGenUtils.CodegenValueType;
+import com.backbase.oss.codegen.utils.DeprecationExtensions;
+import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.media.Schema;
 import lombok.Getter;
 import lombok.Setter;
 import org.openapitools.codegen.CliOption;
+import org.openapitools.codegen.CodegenModel;
+import org.openapitools.codegen.CodegenOperation;
 import org.openapitools.codegen.CodegenProperty;
 import org.openapitools.codegen.SupportingFile;
 import org.openapitools.codegen.languages.JavaClientCodegen;
+import org.openapitools.codegen.model.ModelsMap;
 import org.openapitools.codegen.utils.ModelUtils;
 
 import java.io.File;
+import java.util.Map;
 
 import static com.backbase.oss.codegen.java.BoatCodeGenUtils.getCollectionCodegenValue;
 
@@ -42,6 +48,33 @@ public BoatJavaCodeGen() {
         this.setGenerateClientAsBean(true);
     }
 
+    @Override
+    public void preprocessOpenAPI(OpenAPI openAPI) {
+        super.preprocessOpenAPI(openAPI);
+        DeprecationExtensions.populateDeprecationAdditionalProperties(openAPI, additionalProperties);
+    }
+
+    @Override
+    public CodegenOperation fromOperation(String path, String httpMethod, io.swagger.v3.oas.models.Operation operation,
+                                          java.util.List<io.swagger.v3.oas.models.servers.Server> servers) {
+        CodegenOperation codegenOperation = super.fromOperation(path, httpMethod, operation, servers);
+        BoatCodeGenUtils.applyDeprecationIfNeeded(codegenOperation, additionalProperties);
+        return codegenOperation;
+    }
+
+    @Override
+    public void postProcessModelProperty(CodegenModel model, CodegenProperty property) {
+        super.postProcessModelProperty(model, property);
+        BoatCodeGenUtils.applyDeprecationToPropertyIfNeeded(property, additionalProperties);
+    }
+
+    @Override
+    public Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs) {
+        Map<String, ModelsMap> result = super.postProcessAllModels(objs);
+        BoatCodeGenUtils.applyDeprecationToAllModelsIfNeeded(result, additionalProperties);
+        return result;
+    }
+
     @Override
     public String getName() {
         return NAME;

boat-scaffold/src/main/java/com/backbase/oss/codegen/java/BoatSpringCodeGen.java

@@ -8,8 +8,10 @@
 import static org.openapitools.codegen.utils.StringUtils.camelize;
 
 import com.backbase.oss.codegen.java.BoatCodeGenUtils.CodegenValueType;
+import com.backbase.oss.codegen.utils.DeprecationExtensions;
 import com.samskivert.mustache.Mustache;
 import com.samskivert.mustache.Template.Fragment;
+import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.Operation;
 import io.swagger.v3.oas.models.media.Schema;
 import io.swagger.v3.oas.models.parameters.Parameter;
@@ -20,6 +22,7 @@
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Locale;
+import java.util.Map;
 import java.util.Set;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -38,6 +41,7 @@
 import org.openapitools.codegen.SupportingFile;
 import org.openapitools.codegen.config.GlobalSettings;
 import org.openapitools.codegen.languages.SpringCodegen;
+import org.openapitools.codegen.model.ModelsMap;
 import org.openapitools.codegen.templating.mustache.IndentedLambda;
 import org.openapitools.codegen.utils.ModelUtils;
 
@@ -194,9 +198,9 @@
         this.apiNameSuffix = "Api";
     }
 
     /*
      * Overridden to be able to override the private <code>replaceBeanValidationCollectionType</code> method.
      */
     @Override
     public CodegenParameter fromParameter(Parameter parameter, Set<String> imports) {
         CodegenParameter codegenParameter = super.fromParameter(parameter, imports);
@@ -209,9 +213,9 @@
         }
     }
 
     /*
      * Overridden to be able to override the private <code>replaceBeanValidationCollectionType</code> method.
      */
     @Override
     public CodegenProperty fromProperty(String name, Schema p, boolean required, boolean schemaIsFromAdditionalProperties) {
         CodegenProperty codegenProperty = super.fromProperty(name, p, required, schemaIsFromAdditionalProperties);
@@ -372,6 +376,12 @@
             && this.apiTemplateFiles.containsKey("apiDelegate.mustache");
     }
 
+    @Override
+    public void preprocessOpenAPI(OpenAPI openAPI) {
+        super.preprocessOpenAPI(openAPI);
+        DeprecationExtensions.populateDeprecationAdditionalProperties(openAPI, additionalProperties);
+    }
+
     /**
         This method has been overridden in order to add a parameter to codegen operation for adding HttpServletRequest to
         the service interface. There is a relevant httpServletParam.mustache file.
@@ -392,6 +402,7 @@
         if (codegenOperation.returnType != null) {
             codegenOperation.returnType = codegenOperation.returnType.replace("@Valid", "");
         }
+        BoatCodeGenUtils.applyDeprecationIfNeeded(codegenOperation, additionalProperties);
         return codegenOperation;
     }
 
@@ -413,6 +424,15 @@
             model.imports.add("BigDecimalCustomSerializer");
             model.imports.add(JSON_SERIALIZE);
         }
+
+        BoatCodeGenUtils.applyDeprecationToPropertyIfNeeded(property, additionalProperties);
+    }
+
+    @Override
+    public Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs) {
+        Map<String, ModelsMap> result = super.postProcessAllModels(objs);
+        BoatCodeGenUtils.applyDeprecationToAllModelsIfNeeded(result, additionalProperties);
+        return result;
     }
 
     private boolean shouldSerializeBigDecimalAsString(CodegenProperty property) {
@@ -428,4 +448,5 @@
         return Stream.of(property.baseType, property.dataType, property.datatypeWithEnum)
             .anyMatch("string"::equalsIgnoreCase);
     }
+
 }

boat-scaffold/src/main/java/com/backbase/oss/codegen/utils/DeprecationExtensions.java

@@ -0,0 +1,80 @@
+package com.backbase.oss.codegen.utils;
+
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import java.util.Map;
+import java.util.Optional;
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+
+public final class DeprecationExtensions {
+    public static final String X_DEPRECATED = "x-deprecated";
+    public static final String X_SUNSET_DATE = "x-sunset-date";
+    public static final String X_BOAT_DEPRECATION_MESSAGE = "x-boat-deprecation-message";
+    private static final String BOAT_API_DEPRECATED = "boatApiDeprecated";
+    private static final String BOAT_API_DEPRECATION_MESSAGE = "boatApiDeprecationMessage";
+
+    private DeprecationExtensions() {
+        // utility class
+    }
+
+    /**
+     * Sets the deprecation related additional properties.
+     *
+     * @param openAPI The spec.
+     * @param properties The additional properties to populate.
+     */
+    public static void populateDeprecationAdditionalProperties(OpenAPI openAPI, Map<String, Object> properties) {
+        boolean specDeprecated = DeprecationExtensions.isSpecDeprecated(openAPI.getInfo());
+        Optional<LocalDate> sunsetDate = DeprecationExtensions.getSunsetDate(openAPI.getInfo());
+        properties.put(BOAT_API_DEPRECATED, specDeprecated);
+        properties.put(BOAT_API_DEPRECATION_MESSAGE,
+                DeprecationExtensions.buildDeprecationMessage(sunsetDate));
+    }
+
+    public static boolean isSpecDeprecated(Info info) {
+        if (info == null || info.getExtensions() == null) {
+            return false;
+        }
+        return isTrue(info.getExtensions().get(X_DEPRECATED));
+    }
+
+    public static Optional<LocalDate> getSunsetDate(Info info) {
+        if (info == null || info.getExtensions() == null) {
+            return Optional.empty();
+        }
+        Object dateValue = info.getExtensions().get(X_SUNSET_DATE);
+        if (dateValue == null) {
+            return Optional.empty();
+        }
+        String dateStr = dateValue.toString().trim();
+        if (dateStr.isEmpty()) {
+            return Optional.empty();
+        }
+        try {
+            LocalDate date = LocalDate.parse(dateStr, DateTimeFormatter.ISO_LOCAL_DATE);
+            return Optional.of(date);
+        } catch (DateTimeParseException e) {
+            return Optional.empty();
+        }
+    }
+
+    public static String buildDeprecationMessage(Optional<LocalDate> sunsetDate) {
+        if (sunsetDate.isEmpty()) {
+            return "This API is deprecated.";
+        }
+        return "This API is deprecated and will be removed on " + sunsetDate.get() + ".";
+    }
+
+    private static boolean isTrue(Object value) {
+        if (value instanceof Boolean) {
+            return (Boolean) value;
+        }
+        if (value instanceof String) {
+            return ((String) value).equalsIgnoreCase("true");
+        }
+        return false;
+    }
+}

boat-scaffold/src/main/templates/boat-docs/index.mustache

@@ -44,7 +44,7 @@
               {{#operation}}
                 <div id="api-{{baseName}}-{{nickname}}">
                   <article id="api-{{baseName}}-{{nickname}}-0" data-group="User" data-name="{{nickname}}" data-version="0">
-                          <h1>{{#summary}}{{.}}{{/summary}}{{^summary}}{{nickname}}{{/summary}}{{#isDeprecated}}<span class="deprecated">Deprecated</span> {{/isDeprecated}}</h1>
+                          <h1>{{#summary}}{{.}}{{/summary}}{{^summary}}{{nickname}}{{/summary}}{{#isDeprecated}}<span class="deprecated">Deprecated{{#vendorExtensions.x-boat-deprecation-message}}: {{.}}{{/vendorExtensions.x-boat-deprecation-message}}</span> {{/isDeprecated}}</h1>
                           {{#description}}<p>{{description}}</p>{{/description}}
                     <p class="marked">{{notes}}</p>
                       <br/>

boat-scaffold/src/main/templates/boat-docs/param.mustache

@@ -55,7 +55,7 @@
                     </div>
                 </div>
             {{/isEnum}}
-   {{#deprecated}} <span class="deprecated">Deprecated</span> {{/deprecated}}
+   {{#deprecated}} <span class="deprecated">Deprecated{{#vendorExtensions.x-boat-deprecation-message}}: {{.}}{{/vendorExtensions.x-boat-deprecation-message}}</span> {{/deprecated}}
         </div>
         {{#hasExamples}}
             <div class="examples">

boat-scaffold/src/main/templates/boat-java/api.mustache

@@ -52,7 +52,7 @@ public class {{classname}} {
    {{/returnType}}
    * @throws ApiException if fails to make API call
    {{#isDeprecated}}
-   * @deprecated
+   * @deprecated{{#vendorExtensions.x-boat-deprecation-message}} {{.}}{{/vendorExtensions.x-boat-deprecation-message}}
    {{/isDeprecated}}
    {{#externalDocs}}
    * {{description}}