Add support "unsafe to use" endpoints (#18)

* Ensure propagation of unsafe to use operations (in case the operations is marked as unsafe a @Deprecation warning is set)
* Bump pre-commit hooks
* Trigger git hooks install only if not previously installed
* PR feedbacks + documentation enhancement

Author: macisamuele

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v2.0.0
+  rev: v2.1.0
   hooks:
   - id: check-merge-conflict
   - id: trailing-whitespace
@@ -12,7 +12,7 @@ repos:
   - id: check-yaml
   - id: check-executables-have-shebangs
 - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
-  rev: v1.2.2
+  rev: v1.2.3
   hooks:
   - id: pretty-format-java
     args: [--autofix]
@@ -21,7 +21,7 @@ repos:
   - id: pretty-format-yaml
     args: [--autofix, --indent, '2']
 - repo: https://github.com/Yelp/detect-secrets
-  rev: v0.11.3
+  rev: v0.12.0
   hooks:
   - id: detect-secrets
     args: [--baseline, .secrets.baseline]

.secrets.baseline

@@ -1,6 +1,9 @@
 {
-  "exclude_regex": null,
-  "generated_at": "2019-01-28T12:41:36Z",
+  "exclude": {
+    "files": null,
+    "lines": null
+  },
+  "generated_at": "2019-02-14T20:34:51Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -32,5 +35,5 @@
       }
     ]
   },
-  "version": "0.11.3"
+  "version": "0.12.0"
 }

Makefile

@@ -1,8 +1,11 @@
 .PHONY: install-hooks
 
+.git/hooks/pre-commit: venv
+	${CURDIR}/venv/bin/pre-commit install --install-hooks
+
+install-hooks: .git/hooks/pre-commit
+	@true
+
 venv:
 	virtualenv venv
 	./venv/bin/pip install pre-commit
-
-install-hooks: venv
-	./venv/bin/pre-commit install --install-hooks

plugin/src/main/java/com/yelp/codegen/SharedCodegen.kt

@@ -12,6 +12,7 @@ import io.swagger.codegen.SupportingFile
 import io.swagger.models.ArrayModel
 import io.swagger.models.Model
 import io.swagger.models.ModelImpl
+import io.swagger.models.Operation
 import io.swagger.models.Swagger
 import io.swagger.models.properties.ArrayProperty
 import io.swagger.models.properties.MapProperty
@@ -30,12 +31,14 @@ const val HEADERS_TO_IGNORE = "headers_to_ignore"
 internal const val X_NULLABLE = "x-nullable"
 internal const val X_MODEL = "x-model"
 internal const val X_OPERATION_ID = "x-operation-id"
+internal const val X_UNSAFE_OPERATION = "x-unsafe-operation"
 
 abstract class SharedCodegen : DefaultCodegen(), CodegenConfig {
 
     // Reference to the Swagger Specs
     protected var swagger: Swagger? = null
     private val xModelMatches = mutableMapOf<String, String>()
+    private val unsafeOperations: MutableList<String> = mutableListOf()
 
     override fun getTag() = CodegenType.CLIENT
 
@@ -81,6 +84,11 @@ abstract class SharedCodegen : DefaultCodegen(), CodegenConfig {
     override fun preprocessSwagger(swagger: Swagger) {
         super.preprocessSwagger(swagger)
 
+        unsafeOperations.addAll(when (val it = swagger.info.vendorExtensions["x-operation-ids-unsafe-to-use"]) {
+            is List<*> -> it.filterIsInstance()
+            else -> listOf()
+        })
+
         mapXModel(swagger)
         this.swagger = swagger
     }
@@ -358,6 +366,32 @@ abstract class SharedCodegen : DefaultCodegen(), CodegenConfig {
         return codegenModel.dataType
     }
 
+    /**
+     * Convert Swagger Operation object to Codegen Operation object
+     *
+     * The function takes care of adding additional vendor extensions on the Codegen Operation
+     * to better support the swagger-gradle-codegen use-case
+     *  1) X_OPERATION_ID : added as we want to render operation ids on the final API artifacts
+     *  2) X_UNSAFE_OPERATION : added as we want to mark as deprecated APIs for which we're not sure
+     *                          that will work exactly as expected in the generated code
+     *
+     * @return the converted codegen operation
+     */
+    override fun fromOperation(
+        path: String?,
+        httpMethod: String?,
+        operation: Operation?,
+        definitions: MutableMap<String, Model>?,
+        swagger: Swagger?
+    ): CodegenOperation {
+        val codegenOperation = super.fromOperation(path, httpMethod, operation, definitions, swagger)
+        codegenOperation.vendorExtensions[X_OPERATION_ID] = operation?.operationId
+        if (unsafeOperations.contains(operation?.operationId)) {
+            codegenOperation.vendorExtensions[X_UNSAFE_OPERATION] = true
+        }
+        return codegenOperation
+    }
+
     /**
      * Abstract function to create a type for a JSON Array.
      * @param listType A List Type (e.g. `List`, `ArrayList`, etc)

plugin/src/main/resources/kotlin/retrofit2/api.mustache

@@ -37,8 +37,13 @@ interface {{classname}} {
   @Headers({{#vendorExtensions.x-operation-id}}{{{newline}}}    "X-Operation-ID: {{vendorExtensions.x-operation-id}}"{{/vendorExtensions.x-operation-id}}{{^formParams}}{{#prioritizedContentTypes}}{{#-first}},
     "Content-Type:{{{mediaType}}}"{{/-first}}{{/prioritizedContentTypes}}{{/formParams}}
   )
-  @{{httpMethod}}("{{{path}}}"){{#isDeprecated}}
-  @Deprecated(message = "Deprecated"){{/isDeprecated}}
+
+  @{{httpMethod}}("{{{path}}}"){{#vendorExtensions.x-unsafe-operation}}{{#isDeprecated}}
+      @Deprecated(message = "Deprecated and unsafe to use"){{/isDeprecated}}{{^isDeprecated}}
+      @Deprecated(message = "Unsafe to use"){{/isDeprecated}}
+  {{/vendorExtensions.x-unsafe-operation}}{{^vendorExtensions.x-unsafe-operation}}{{#isDeprecated}}
+      @Deprecated(message = "Deprecated"){{/isDeprecated}}
+  {{/vendorExtensions.x-unsafe-operation}}
   fun {{operationId}}({{^allParams}}){{/allParams}}
     {{#allParams}}{{>retrofit2/queryParams}}{{>retrofit2/pathParams}}{{>retrofit2/headerParams}}{{>retrofit2/bodyParams}}{{>retrofit2/formParams}}{{#hasMore}},
     {{/hasMore}}{{^hasMore}}