You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2017/10/03 14:24:07 UTC
[30/35] brooklyn-server git commit: add deprecation notes to
description for REST endpoints so they appear in swagger
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 <al...@cloudsoftcorp.com>
Authored: Tue Oct 3 09:31:52 2017 +0100
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
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")
})