add deprecation notes to description for REST endpoints so they appear in swagger
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-server/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-server/commit/e0160538 Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-server/tree/e0160538 Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-server/diff/e0160538 Branch: refs/heads/master Commit: e0160538fee0dd8f0308ed4d6787d54bf813d7dc Parents: 4f4507a Author: Alex Heneveld <[email protected]> Authored: Tue Oct 3 09:31:52 2017 +0100 Committer: Alex Heneveld <[email protected]> Committed: Tue Oct 3 09:31:52 2017 +0100 ---------------------------------------------------------------------- .../apache/brooklyn/rest/api/CatalogApi.java | 34 +++++++++++--------- .../org/apache/brooklyn/rest/api/PolicyApi.java | 14 ++++---- .../brooklyn/rest/api/PolicyConfigApi.java | 8 ++--- 3 files changed, 29 insertions(+), 27 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/e0160538/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/CatalogApi.java ---------------------------------------------------------------------- diff --git a/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/CatalogApi.java b/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/CatalogApi.java index 6499f14..2c115df 100644 --- a/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/CatalogApi.java +++ b/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/CatalogApi.java @@ -58,7 +58,7 @@ public interface CatalogApi { @Consumes("application/json-deprecated") // prevent this from taking things @POST @ApiOperation( - value = "Add a catalog items (e.g. new type of entity, policy or location) by uploading YAML descriptor.", + value = "Add a catalog items (e.g. new type of entity, policy or location) by uploading YAML descriptor (deprecated, use POST of yaml or ZIP/JAR instead)", notes = "Return value is map of ID to CatalogItemSummary.", response = String.class, hidden = true @@ -159,7 +159,7 @@ public interface CatalogApi { @DELETE @Path("/applications/{symbolicName}/{version}") @ApiOperation( - value = "Deletes a specific version of an application's definition from the catalog", + value = "Deletes a specific version of an application's definition from the catalog (deprecated, use /catalog/bundles endpoint instead)", notes = "Version must exists, otherwise the API will return a 404. Alternatively, passing 'latest' will" + "pick up the latest version for the given 'symbolicName'" ) @@ -179,7 +179,7 @@ public interface CatalogApi { @DELETE @Path("/entities/{symbolicName}/{version}") @ApiOperation( - value = "Deletes a specific version of an entity's definition from the catalog", + value = "Deletes a specific version of an entity's definition from the catalog (deprecated, use /catalog/bundles endpoint instead, as we add/delete bundles now)", notes = "Version must exists, otherwise the API will return a 404. Alternatively, passing 'latest' will" + "pick up the latest version for the given 'symbolicName'" ) @@ -199,7 +199,7 @@ public interface CatalogApi { @DELETE @Path("/policies/{policyId}/{version}") @ApiOperation( - value = "Deletes a specific version of an policy's definition from the catalog", + value = "Deletes a specific version of an policy's definition from the catalog (deprecated, use /catalog/bundles endpoint instead, as we add/delete bundles now)", notes = "Version must exists, otherwise the API will return a 404. Alternatively, passing 'latest' will" + "pick up the latest version for the given 'policyId'") @ApiResponses(value = { @@ -218,7 +218,7 @@ public interface CatalogApi { @DELETE @Path("/locations/{locationId}/{version}") @ApiOperation( - value = "Deletes a specific version of an location's definition from the catalog", + value = "Deletes a specific version of an location's definition from the catalog (deprecated, use /catalog/bundles endpoint instead, as we add/delete bundles now)", notes = "Version must exists, otherwise the API will return a 404. Alternatively, passing 'latest' will" + "pick up the latest version for the given 'locationId'" ) @@ -237,7 +237,7 @@ public interface CatalogApi { @Deprecated @GET @Path("/entities") - @ApiOperation(value = "List available entity types optionally matching a query", + @ApiOperation(value = "List available entity types optionally matching a query (deprecated, use /catalog/types endpoint instead, with supertype=entity)", response = CatalogItemSummary.class, responseContainer = "List") public List<CatalogEntitySummary> listEntities( @@ -254,7 +254,7 @@ public interface CatalogApi { @Deprecated @GET @Path("/applications") - @ApiOperation(value = "Fetch a list of templates (for applications) optionally matching a query", + @ApiOperation(value = "Fetch a list of templates (for applications) optionally matching a query (deprecated, use /catalog/types endpoint instead, with supertype=application; note some semantics of templates are changing as definition becomes more precise)", response = CatalogItemSummary.class, responseContainer = "List") public List<CatalogItemSummary> listApplications( @@ -271,7 +271,7 @@ public interface CatalogApi { @GET @Path("/entities/{symbolicName}/{version}") @ApiOperation( - value = "Fetch a specific version of an entity's definition from the catalog", + value = "Fetch a specific version of an entity's definition from the catalog (deprecated, use /catalog/types endpoint instead)", notes = "Version must exists, otherwise the API will return a 404. Alternatively, passing 'latest' will" + "pick up the latest version for the given 'symbolicName'", response = CatalogEntitySummary.class, @@ -292,7 +292,7 @@ public interface CatalogApi { @GET @Path("/applications/{symbolicName}/{version}") @ApiOperation( - value = "Fetch a specific version of an application's definition from the catalog", + value = "Fetch a specific version of an application's definition from the catalog (deprecated, use /catalog/types endpoint instead)", notes = "Version must exists, otherwise the API will return a 404. Alternatively, passing 'latest' will" + "pick up the latest version for the given 'symbolicName'", response = CatalogEntitySummary.class, @@ -312,7 +312,7 @@ public interface CatalogApi { @Deprecated @GET @Path("/policies") - @ApiOperation(value = "List available policies optionally matching a query", + @ApiOperation(value = "List available policies optionally matching a query (deprecated, use /catalog/types endpoint instead)", response = CatalogPolicySummary.class, responseContainer = "List") public List<CatalogPolicySummary> listPolicies( @@ -329,7 +329,7 @@ public interface CatalogApi { @GET @Path("/policies/{policyId}/{version}") @ApiOperation( - value = "Fetch a policy's definition from the catalog", + value = "Fetch a policy's definition from the catalog (deprecated, use /catalog/types endpoint instead)", notes = "Version must exists, otherwise the API will return a 404. Alternatively, passing 'latest' will" + "pick up the latest version for the given 'policyId'", response = CatalogItemSummary.class, @@ -348,7 +348,7 @@ public interface CatalogApi { @Deprecated @GET @Path("/locations") - @ApiOperation(value = "List available locations optionally matching a query", + @ApiOperation(value = "List available locations optionally matching a query (deprecated, use /catalog/types endpoint instead)", response = CatalogLocationSummary.class, responseContainer = "List") public List<CatalogLocationSummary> listLocations( @@ -365,7 +365,7 @@ public interface CatalogApi { @GET @Path("/locations/{locationId}/{version}") @ApiOperation( - value = "Fetch a location's definition from the catalog", + value = "Fetch a location's definition from the catalog (deprecated, use /catalog/types endpoint instead)", notes = "Version must exists, otherwise the API will return a 404. Alternatively, passing 'latest' will" + "pick up the latest version for the given 'locationId'", response = CatalogItemSummary.class, @@ -406,6 +406,7 @@ public interface CatalogApi { @ApiResponses(value = { @ApiResponse(code = 404, message = "Undefined catalog item"), }) + @ApiOperation(value = "Deprecate an item (deprecated, use /catalog/types endpoint instead, but disabled/deprecating is not supported for individual types)") @Path("/entities/{itemId}/deprecated") public void setDeprecated( @ApiParam(name = "itemId", value = "The ID of the catalog item to be deprecated", required = true) @@ -419,6 +420,7 @@ public interface CatalogApi { @Deprecated @POST @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_OCTET_STREAM, MediaType.TEXT_PLAIN}) + @ApiOperation(value = "Disable an item (deprecated, use /catalog/types endpoint instead, but disabled/deprecating is not supported for individual types)") @ApiResponses(value = { @ApiResponse(code = 404, message = "Undefined catalog item"), }) @@ -434,7 +436,7 @@ public interface CatalogApi { @Deprecated @GET @Path("/enrichers") - @ApiOperation(value = "List available enrichers types optionally matching a query", + @ApiOperation(value = "List available enrichers types optionally matching a query (deprecated, use /catalog/types endpoint instead)", response = CatalogItemSummary.class, responseContainer = "List") public List<CatalogEnricherSummary> listEnrichers( @@ -450,7 +452,7 @@ public interface CatalogApi { @Deprecated @GET @Path("/enrichers/{enricherId}/{version}") - @ApiOperation(value = "Fetch an enricher's definition from the catalog", + @ApiOperation(value = "Fetch an enricher's definition from the catalog (deprecated, use /catalog/types endpoint instead)", response = CatalogItemSummary.class, responseContainer = "List") @ApiResponses(value = { @@ -467,7 +469,7 @@ public interface CatalogApi { @Deprecated @DELETE @Path("/enrichers/{enricherId}/{version}") - @ApiOperation(value = "Deletes a specific version of an enricher's definition from the catalog") + @ApiOperation(value = "Deletes a specific version of an enricher's definition from the catalog (deprecated, use /catalog/types endpoint instead)") @ApiResponses(value = { @ApiResponse(code = 404, message = "Enricher not found") }) http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/e0160538/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/PolicyApi.java ---------------------------------------------------------------------- diff --git a/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/PolicyApi.java b/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/PolicyApi.java index 329c0e1..95f41db 100644 --- a/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/PolicyApi.java +++ b/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/PolicyApi.java @@ -41,7 +41,7 @@ import java.util.Map; public interface PolicyApi { @GET - @ApiOperation(value = "Fetch the policies attached to a specific application entity", + @ApiOperation(value = "Fetch the policies attached to a specific application entity (deprecated, use adjuncts/ endpoint instead)", response = org.apache.brooklyn.rest.domain.PolicySummary.class, responseContainer = "List") @ApiResponses(value = { @@ -57,7 +57,7 @@ public interface PolicyApi { // (and in sensors class) @GET @Path("/current-state") - @ApiOperation(value = "Fetch policy states in batch", notes="Returns a map of policy ID to whether it is active") + @ApiOperation(value = "Fetch policy states in batch", notes="Returns a map of policy ID to whether it is active (deprecated, use adjuncts/ endpoint instead)") // FIXME method name -- this is nothing to do with config! public Map<String, Boolean> batchConfigRead( @ApiParam(value = "Application ID or name", required = true) @@ -66,7 +66,7 @@ public interface PolicyApi { @PathParam("entity") String entityToken) ; @POST - @ApiOperation(value = "Add a policy", notes = "Returns a summary of the new policy") + @ApiOperation(value = "Add a policy", notes = "Returns a summary of the new policy (deprecated, use adjuncts/ endpoint instead)") @ApiResponses(value = { @ApiResponse(code = 404, message = "Could not find application or entity"), @ApiResponse(code = 400, message = "Type is not a class implementing Policy") @@ -88,7 +88,7 @@ public interface PolicyApi { @GET @Path("/{policy}") - @ApiOperation(value = "Gets status of a policy (RUNNING / SUSPENDED)") + @ApiOperation(value = "Gets status of a policy (RUNNING / SUSPENDED) (deprecated, use adjuncts/ endpoint instead)") @ApiResponses(value = { @ApiResponse(code = 404, message = "Could not find application, entity or policy") }) @@ -104,7 +104,7 @@ public interface PolicyApi { @POST @Path("/{policy}/start") - @ApiOperation(value = "Start or resume a policy") + @ApiOperation(value = "Start or resume a policy (deprecated, use adjuncts/ endpoint instead)") @ApiResponses(value = { @ApiResponse(code = 404, message = "Could not find application, entity or policy") }) @@ -120,7 +120,7 @@ public interface PolicyApi { @POST @Path("/{policy}/stop") - @ApiOperation(value = "Suspends a policy") + @ApiOperation(value = "Suspends a policy (deprecated, use adjuncts/ endpoint instead)") @ApiResponses(value = { @ApiResponse(code = 404, message = "Could not find application, entity or policy") }) @@ -137,7 +137,7 @@ public interface PolicyApi { // TODO: Should be DELETE /policy, not POST /policy/destroy @POST @Path("/{policy}/destroy") - @ApiOperation(value = "Destroy a policy", notes="Removes a policy from being associated with the entity and destroys it (stopping first if running)") + @ApiOperation(value = "Destroy a policy (deprecated, use adjuncts/ endpoint instead)", notes="Removes a policy from being associated with the entity and destroys it (stopping first if running)") @ApiResponses(value = { @ApiResponse(code = 404, message = "Could not find application, entity or policy") }) http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/e0160538/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/PolicyConfigApi.java ---------------------------------------------------------------------- diff --git a/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/PolicyConfigApi.java b/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/PolicyConfigApi.java index 06a4b86..8d061dd 100644 --- a/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/PolicyConfigApi.java +++ b/rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/PolicyConfigApi.java @@ -47,7 +47,7 @@ import io.swagger.annotations.ApiResponses; public interface PolicyConfigApi { @GET - @ApiOperation(value = "Fetch the config keys for a specific policy", + @ApiOperation(value = "Fetch the config keys for a specific policy (deprecated, use adjuncts/ endpoint instead)", response = org.apache.brooklyn.rest.domain.ConfigSummary.class, responseContainer = "List") @ApiResponses(value = { @@ -65,7 +65,7 @@ public interface PolicyConfigApi { // (and in sensors class) @GET @Path("/current-state") - @ApiOperation(value = "Fetch config key values in batch", notes="Returns a map of config name to value") + @ApiOperation(value = "Fetch config key values in batch (deprecated, use adjuncts/ endpoint instead)", notes="Returns a map of config name to value") public Map<String, Object> batchConfigRead( @ApiParam(value = "Application ID or name", required = true) @PathParam("application") String application, @@ -76,7 +76,7 @@ public interface PolicyConfigApi { @GET @Path("/{config}") - @ApiOperation(value = "Fetch config value", response = Object.class) + @ApiOperation(value = "Fetch config value (deprecated, use adjuncts/ endpoint instead)", response = Object.class) @ApiResponses(value = { @ApiResponse(code = 404, message = "Could not find application, entity, policy or config key") }) @@ -93,7 +93,7 @@ public interface PolicyConfigApi { @POST @Path("/{config}") @Consumes(value = {"*/*"}) - @ApiOperation(value = "Sets the given config on this policy") + @ApiOperation(value = "Sets the given config on this policy (deprecated, use adjuncts/ endpoint instead)") @ApiResponses(value = { @ApiResponse(code = 404, message = "Could not find application, entity, policy or config key") })
