update api docs

bubble-server/src/main/java/bubble/ApiConstants.java

@@ -302,6 +302,7 @@ public class ApiConstants {
     public static final String API_TAG_APP_RUNTIME = "Bubble App-Runtime";
     public static final String API_TAG_DEVICES = "Devices";
     public static final String API_TAG_BACKUP_RESTORE = "Backup and Restore";
+    public static final String API_TAG_BUBBLE_INFO = "Bubble Information";
     public static final String API_TAG_CLOUDS = "Cloud Services";
     public static final String API_TAG_DEBUG = "Debug";
     public static final String API_TAG_MITMPROXY = "Mitmproxy";
@@ -309,6 +310,7 @@ public class ApiConstants {
     public static final String API_TAG_NODE_MANAGER = "Node Manager";
     public static final String API_TAG_PAYMENT = "Payment";
     public static final String API_TAG_SEARCH = "Search";
+    public static final String API_TAG_UPGRADE = "Upgrades";
 
     public static String getToken(String json) {
         if (json == null) return null;

bubble-server/src/main/java/bubble/resources/BubbleMagicResource.java

@@ -17,11 +17,11 @@ import javax.ws.rs.Produces;
 import javax.ws.rs.core.Context;
 import javax.ws.rs.core.Response;
 
+import static bubble.ApiConstants.API_TAG_BUBBLE_INFO;
 import static bubble.ApiConstants.BUBBLE_MAGIC_ENDPOINT;
 import static org.cobbzilla.util.http.HttpContentTypes.APPLICATION_JSON;
 import static org.cobbzilla.util.http.HttpStatusCodes.SC_OK;
 import static org.cobbzilla.wizard.resources.ResourceUtil.ok;
-import static org.cobbzilla.wizard.server.config.OpenApiConfiguration.API_TAG_UTILITY;
 
 @Consumes(APPLICATION_JSON)
 @Produces(APPLICATION_JSON)
@@ -30,7 +30,7 @@ import static org.cobbzilla.wizard.server.config.OpenApiConfiguration.API_TAG_UT
 public class BubbleMagicResource {
 
     @GET
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Simple health check",
             description="Returns a static string, verifies that API can communicate over the network",
             responses=@ApiResponse(responseCode=SC_OK, description="fixed response")

bubble-server/src/main/java/bubble/resources/DetectResource.java

@@ -25,7 +25,6 @@ import static org.cobbzilla.util.http.HttpContentTypes.APPLICATION_JSON;
 import static org.cobbzilla.util.http.HttpStatusCodes.SC_OK;
 import static org.cobbzilla.wizard.resources.ResourceUtil.ok;
 import static org.cobbzilla.wizard.resources.ResourceUtil.optionalUserPrincipal;
-import static org.cobbzilla.wizard.server.config.OpenApiConfiguration.API_TAG_UTILITY;
 
 @Consumes(APPLICATION_JSON)
 @Produces(APPLICATION_JSON)
@@ -36,7 +35,7 @@ public class DetectResource {
     @Autowired private GeoService geoService;
 
     @GET @Path(EP_LOCALE)
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Detect the caller's locale",
             description="Detect the caller's locale",
             responses=@ApiResponse(responseCode=SC_OK, description="an array of locale strings in priority order")
@@ -47,7 +46,7 @@ public class DetectResource {
     }
 
     @GET @Path(EP_TIMEZONE)
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Detect the caller's time zone",
             description="Detect the caller's time zone",
             responses=@ApiResponse(responseCode=SC_OK, description="the TimeZone ")

bubble-server/src/main/java/bubble/resources/IdentityResource.java

@@ -28,11 +28,11 @@ import javax.ws.rs.core.Response;
 import java.util.HashMap;
 import java.util.Map;
 
+import static bubble.ApiConstants.API_TAG_BUBBLE_INFO;
 import static bubble.ApiConstants.ID_ENDPOINT;
 import static org.cobbzilla.util.http.HttpContentTypes.APPLICATION_JSON;
 import static org.cobbzilla.util.http.HttpStatusCodes.SC_OK;
 import static org.cobbzilla.wizard.resources.ResourceUtil.*;
-import static org.cobbzilla.wizard.server.config.OpenApiConfiguration.API_TAG_UTILITY;
 import static org.cobbzilla.wizard.server.config.OpenApiConfiguration.SEC_API_KEY;
 
 @Consumes(APPLICATION_JSON)
@@ -49,7 +49,7 @@ public class IdentityResource {
 
     @GET @Path("/{id}")
     @Operation(security=@SecurityRequirement(name=SEC_API_KEY),
-            tags=API_TAG_UTILITY,
+            tags=API_TAG_BUBBLE_INFO,
             summary="Find what object(s) an ID belongs to. Useful when you have a UUID but don't know what kind of thing it refers to, if any.",
             description="Searches all model objects by ID. The id parameter is typically a UUID or name",
             parameters=@Parameter(name="id", description="an identifier (typically UUID or name) to search for", required=true),

bubble-server/src/main/java/bubble/resources/account/AccountsResource.java

@@ -629,7 +629,7 @@ public class AccountsResource {
 
     @GET @Path("/{id}"+EP_MITM)
     @Operation(security=@SecurityRequirement(name=SEC_API_KEY),
-            tags=API_TAG_UTILITY,
+            tags={API_TAG_BUBBLE_INFO, API_TAG_UTILITY},
             summary="Get status of mitmproxy",
             description="Get status of mitmproxy. Caller must be admin.",
             parameters=@Parameter(name="id", description="UUID or email of the Account", required=true),
@@ -754,7 +754,7 @@ public class AccountsResource {
 
     @GET @Path("/{id}"+EP_DEVICE_TYPES)
     @Operation(security=@SecurityRequirement(name=SEC_API_KEY),
-            tags=API_TAG_UTILITY,
+            tags=API_TAG_BUBBLE_INFO,
             summary="List selectable device types",
             description="List selectable device types. This excludes pseudo-devices like Firefox and web-clients.",
             parameters=@Parameter(name="id", description="UUID or email of the Account", required=true),

bubble-server/src/main/java/bubble/resources/account/AuthResource.java

@@ -132,7 +132,7 @@ public class AuthResource {
     }
 
     @GET @Path(EP_CONFIGS)
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Read public system configuration",
             description="Read public system configuration",
             responses=@ApiResponse(responseCode=SC_OK, description="a Map<String, Object> of public system configuration settings")
@@ -142,7 +142,7 @@ public class AuthResource {
     }
 
     @GET @Path(EP_READY)
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Determine if Bubble is running and ready for login",
             description="Determine if Bubble is running and ready for login",
             responses={
@@ -884,7 +884,7 @@ public class AuthResource {
 
     @GET @Path(EP_CA_CERT)
     @Produces(CONTENT_TYPE_ANY)
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Get the CA Certificate for this Bubble",
             description="Get the CA Certificate for this Bubble. Response body is the certificate itself, in a format determined by deviceType or type. Either deviceType or type can be supplied but not both. Device types are: `ios`, `android`, `windows`, `macos` and `linux`. Cert types are: `pem`, `p12`, `cer`, `crt`",
             parameters={
@@ -922,7 +922,7 @@ public class AuthResource {
     }
 
     @GET @Path(EP_KEY)
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Get the Node Key for this Bubble",
             description="Get the Node Key for this Bubble",
             responses=@ApiResponse(responseCode=SC_OK, description="HTTP status 200 indicates success")
@@ -995,7 +995,7 @@ public class AuthResource {
     }
 
     @GET @Path(EP_TIME)
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Get current system time",
             description="Get current system time. Returns current time as epoch time in milliseconds",
             responses=@ApiResponse(responseCode=SC_OK, description="Returns current time as epoch time in milliseconds",
@@ -1006,7 +1006,7 @@ public class AuthResource {
     @Autowired private GeoService geoService;
 
     @GET @Path(EP_SUPPORT)
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Get support information",
             description="Get support information for the user's current locale, if available. Use the default locale otherwise.",
             responses=@ApiResponse(responseCode=SC_OK, description="SupportInfo object")
@@ -1018,7 +1018,7 @@ public class AuthResource {
     }
 
     @GET @Path(EP_SUPPORT+"/{locale}")
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Get support information for a locale",
             description="Get support information for the given locale, if available. Use the default locale otherwise.",
             parameters=@Parameter(name="locale", description="locale to find support for", required=true),
@@ -1031,7 +1031,7 @@ public class AuthResource {
     }
 
     @GET @Path(EP_APP_LINKS)
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Get links to native applications",
             description="Get links to native applications for the current user's locale, if available. Use the default locale otherwise.",
             responses=@ApiResponse(responseCode=SC_OK, description="AppLinks object")
@@ -1043,7 +1043,7 @@ public class AuthResource {
     }
 
     @GET @Path(EP_APP_LINKS+"/{locale}")
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Get links to native applications for a locale",
             description="Get links to native applications for the given locale, if available. Use the default locale otherwise.",
             parameters=@Parameter(name="locale", description="locale to find app links for", required=true),
@@ -1079,7 +1079,7 @@ public class AuthResource {
     @Produces(APPLICATION_OCTET_STREAM)
     @Operation(tags=API_TAG_NODE,
             summary="Return bubble jar",
-            description="Return bubble jar file for upgrading other nodes to our version.",
+            description="Called by another node to fetch our bubble jar for upgrade purposes.",
             parameters={
                     @Parameter(name="node", description="UUID of the calling node", required=true),
                     @Parameter(name="key", description="UUID of the calling node's BubbleNodeKey", required=true)

bubble-server/src/main/java/bubble/resources/account/MeResource.java

@@ -171,7 +171,7 @@ public class MeResource {
     }
 
     @GET @Path(EP_ERROR_API)
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Get error API information",
             description="Get error API information",
             responses=@ApiResponse(responseCode=SC_OK, description="a Map of API information")
@@ -554,7 +554,7 @@ public class MeResource {
 
     @GET @Path(EP_UPGRADE)
     @Operation(security=@SecurityRequirement(name=SEC_API_KEY),
-            tags=API_TAG_UTILITY,
+            tags=API_TAG_UPGRADE,
             summary="Check for upgrade",
             description="Check for upgrade. Must be admin. The check runs in the background, this returns an empty JSON object",
             responses=@ApiResponse(responseCode=SC_OK, description="the upgrade check has been started", content=@Content(mediaType=APPLICATION_JSON, examples=@ExampleObject(name="empty JSON object", value="{}")))
@@ -577,7 +577,7 @@ public class MeResource {
 
     @POST @Path(EP_UPGRADE)
     @Operation(security=@SecurityRequirement(name=SEC_API_KEY),
-            tags=API_TAG_UTILITY,
+            tags=API_TAG_UPGRADE,
             summary="Upgrade Bubble",
             description="Upgrade Bubble. Must be admin. Starts the upgrade process.",
             responses=@ApiResponse(responseCode=SC_OK, description="the current public system configs")

bubble-server/src/main/java/bubble/resources/cloud/LogsResource.java

@@ -45,7 +45,7 @@ public class LogsResource {
 
     @GET @Path(EP_STATUS)
     @Operation(security=@SecurityRequirement(name=SEC_API_KEY),
-            tags=API_TAG_UTILITY,
+            tags={API_TAG_BUBBLE_INFO, API_TAG_UTILITY},
             summary="Get logging status",
             description="Get logging status. Must be admin. Returns a JSON object with keys `"+K_FLAG+"` (boolean, indicates if logging is enabled) and `"+K_EXPIRE_AT+"` (epoch time in milliseconds when logging will automatically be turned off)",
             responses=@ApiResponse(responseCode=SC_OK, description="true if logs enabled, false otherwise")

bubble-server/src/main/java/bubble/resources/message/MessagesResource.java

@@ -61,7 +61,7 @@ public class MessagesResource {
     }
 
     @GET @Path("/{locale}/{group}")
-    @Operation(tags=API_TAG_UTILITY,
+    @Operation(tags=API_TAG_BUBBLE_INFO,
             summary="Get localized messages",
             description="Get localized messages by group. `locale` specifies the desired locale. If the locale is not supported, another similar locale or the default locale will be used. `The `group` param is the message group to retrieve. Groups are: `pre_auth`, `post_auth`, `countries`, `timezones`, `apps`. Requesting the `post_auth` or `apps` groups requires a valid API session. `format` is an optional format for the messages. Format can be `raw` or `underscore` (which converts dots to underscores). Default is `underscore`.",
             parameters={

bubble-server/src/main/resources/META-INF/bubble/openapi-tags.json

@@ -67,8 +67,20 @@
     "name": "payment",
     "description": "Payment APIs are disabled by default.\n\nFor more information about using Bubble with payments enabled, contact [licensing@getbubblenow.com](mailto:licensing@getbubblenow.com)"
   },
+  {
+    "name": "bubble_info",
+    "description": "Information about this Bubble and about the caller. Locales, timezones, models and more."
+  },
   {
     "name": "search",
     "description": "Search objects in the Bubble database."
+  },
+  {
+    "name": "upgrades",
+    "description": "Check for upgrades. Upgrade your Bubble."
+  },
+  {
+    "name": "utility",
+    "description": "A veritable grab-bag of random utilities, from time zone tools to enabling/disabling the mitmproxy service."
   }
 ]

utils/cobbzilla-wizard

@@ -1 +1 @@
-Subproject commit 329c22899d0c0bafd4953a333e0d9fc1d0b3e275
+Subproject commit b8316b1de2dff8bc33db64e6c9b1b4d324a809c1