Added Open API tags to the rest api.

Author: sebinside

src/main/scala/org/codeoverflow/chatoverflow/ui/web/rest/TagSupport.scala

@@ -0,0 +1,7 @@
+package org.codeoverflow.chatoverflow.ui.web.rest
+
+trait TagSupport {
+
+  protected def controllerTag: String
+
+}

src/main/scala/org/codeoverflow/chatoverflow/ui/web/rest/config/ConfigControllerDefinition.scala

@@ -1,50 +1,52 @@
 package org.codeoverflow.chatoverflow.ui.web.rest.config
 
 import org.codeoverflow.chatoverflow.ui.web.rest.DTOs.{AuthKey, ConfigInfo, Password, ResultMessage}
+import org.codeoverflow.chatoverflow.ui.web.rest.TagSupport
 import org.scalatra.swagger.SwaggerSupport
 import org.scalatra.swagger.SwaggerSupportSyntax.OperationBuilder
 
-trait ConfigControllerDefinition extends SwaggerSupport {
+trait ConfigControllerDefinition extends SwaggerSupport with TagSupport {
 
   val getConfig: OperationBuilder =
     (apiOperation[ConfigInfo]("getConfig")
       summary "Shows general information and settings."
-      description "Shows API version and chat overflow startup settings.")
-
+      description "Shows API version and chat overflow startup settings."
+      tags controllerTag)
   val postSave: OperationBuilder =
     (apiOperation[Boolean]("postSave")
       summary "Triggers the saving process of the framework manually (if loaded previously)."
-      description "Triggers saving of credentials and configuration. Should not be needed manually.")
-
+      description "Triggers saving of credentials and configuration. Should not be needed manually."
+      tags controllerTag)
   val postExit: OperationBuilder =
     (apiOperation[ResultMessage]("postExit")
       summary "Shuts the framework down."
       description "Shutdown the framework in the next second if a correct auth key is supplied."
+      tags controllerTag
       parameter bodyParam[AuthKey]("body").description("Requires the run specific auth key."))
-
-
   val getLogin: OperationBuilder =
     (apiOperation[Boolean]("getLogin")
       summary "Returns if the framework is already loaded."
-      description "Returns true, if the framework had been loaded previously with success.")
-
+      description "Returns true, if the framework had been loaded previously with success."
+      tags controllerTag)
   val postLogin: OperationBuilder =
     (apiOperation[ResultMessage]("postLogin")
       summary "Logs in the the framework with the given password, loads config and credentials."
       description "Tries to decrypt the credentials using the provided password. If already loaded, does only return the communication auth key."
+      tags controllerTag
       parameter bodyParam[Password]("body").description("Requires the user framework password. The auth key is based on this input."))
-
   val getRegister: OperationBuilder =
     (apiOperation[Boolean]("getRegister")
       summary "Returns if a credentials file has been created and thus a specific password been registered."
-      description "Returns true, if the credentials file (with set password) already exists.")
-
+      description "Returns true, if the credentials file (with set password) already exists."
+      tags controllerTag)
   val postRegister: OperationBuilder =
     (apiOperation[ResultMessage]("postRegister")
       summary "Registers the user with the given password. Can only be called if there is no credentials file."
       description "Creates a credentials file with the given password. Acts like post(login) after this (returning an auth key)."
+      tags controllerTag
       parameter bodyParam[Password]("body").description("Requires the user framework password. The auth key is based on this input."))
 
+  override def controllerTag: String = "config"
 
   override protected def applicationDescription: String = "Handles configuration and information retrieval."
 }

src/main/scala/org/codeoverflow/chatoverflow/ui/web/rest/connector/ConnectorControllerDefinition.scala

@@ -2,68 +2,71 @@ package org.codeoverflow.chatoverflow.ui.web.rest.connector
 
 import org.codeoverflow.chatoverflow.connector.ConnectorKey
 import org.codeoverflow.chatoverflow.ui.web.rest.DTOs._
+import org.codeoverflow.chatoverflow.ui.web.rest.TagSupport
 import org.scalatra.swagger.SwaggerSupport
 import org.scalatra.swagger.SwaggerSupportSyntax.OperationBuilder
 
-trait ConnectorControllerDefinition extends SwaggerSupport {
+trait ConnectorControllerDefinition extends SwaggerSupport with TagSupport {
 
   val getConnectors: OperationBuilder =
     (apiOperation[ConnectorKey]("getConnectors")
       summary "Shows all connector keys."
-      description "Shows the unique keys (connector type and source Identifier) of all connectors.")
-
+      description "Shows the unique keys (connector type and source Identifier) of all connectors."
+      tags controllerTag)
   val getConnector: OperationBuilder =
     (apiOperation[ConnectorDetails]("getConnector")
       summary "Shows all information of a specific connector."
       description "Besides unique key, shows additional information like required and optional credentials. "
+      tags controllerTag
       parameter pathParam[String]("sourceIdentifier").description("The (connector unique) identifier of e.g. a account to connect to")
       parameter pathParam[String]("qualifiedConnectorType").description("The fully qualified type of the connector."))
-
   val postConnector: OperationBuilder =
     (apiOperation[ResultMessage]("postConnector")
       summary "Creates a new connector."
       description "Creates a connector with given sourceIdentifier and connector type."
+      tags controllerTag
       parameter bodyParam[ConnectorRef]("body").description("Requires platform specific source identifier and connector type."))
-
   val deleteConnector: OperationBuilder =
     (apiOperation[ResultMessage]("deleteConnector")
       summary "Deletes a specific connector."
       description "Deletes the connector specified by identifier and unique type string."
+      tags controllerTag
       parameter pathParam[String]("sourceIdentifier").description("The (connector unique) identifier of e.g. a account to connect to")
       parameter pathParam[String]("qualifiedConnectorType").description("The fully qualified type of the connector."))
-
   val getCredentials: OperationBuilder =
     (apiOperation[ConnectorDetails]("getCredentials")
       summary "Shows all credentials for a specified connector."
       description "Shows required and optional credentials. Note, that the user has to be logged in and the values are encrypted using the auth key. "
+      tags controllerTag
       parameter pathParam[String]("sourceIdentifier").description("The (connector unique) identifier of e.g. a account to connect to")
       parameter pathParam[String]("qualifiedConnectorType").description("The fully qualified type of the connector."))
-
   val getCredentialsEntry: OperationBuilder =
     (apiOperation[CredentialsEntry]("getCredentialsEntry")
       summary "Shows a specific credentials entry of a specific connector."
       description "Shows one credentials entry if existent. Note, that the user has to be logged in and the value is encrypted using the auth key. "
+      tags controllerTag
       parameter pathParam[String]("sourceIdentifier").description("The (connector unique) identifier of e.g. a account to connect to")
       parameter pathParam[String]("qualifiedConnectorType").description("The fully qualified type of the connector.")
       parameter pathParam[String]("key").description("The key of the credentials entry."))
-
   val postCredentialsEntry: OperationBuilder =
     (apiOperation[ResultMessage]("postCredentialsEntry")
       summary "Creates a new credentials entry."
       description "Creates a new credentials entry with given parameters for a given connector. Note that only required & optional keys can be added."
+      tags controllerTag
       parameter pathParam[String]("sourceIdentifier").description("The (connector unique) identifier of e.g. a account to connect to")
       parameter pathParam[String]("qualifiedConnectorType").description("The fully qualified type of the connector.")
       parameter bodyParam[EncryptedKeyValuePair]("body").description("Requires a key-value pair. The value must be encrypted using the auth key."))
-
   val deleteCredentialsEntry: OperationBuilder =
     (apiOperation[ResultMessage]("deleteCredentialsEntry")
       summary "Deletes a specific credentials entry."
       description "Deletes a specific credentials entry of a given connector, if possible."
+      tags controllerTag
       parameter pathParam[String]("sourceIdentifier").description("The (connector unique) identifier of e.g. a account to connect to")
       parameter pathParam[String]("qualifiedConnectorType").description("The fully qualified type of the connector.")
       parameter pathParam[String]("key").description("The key of the credentials entry.")
       parameter bodyParam[AuthKey]("body").description("Requires the client auth key since this is a sensible operation."))
 
+  override def controllerTag: String = "connector"
 
   override protected def applicationDescription: String = "Handles platform connectors."
 

src/main/scala/org/codeoverflow/chatoverflow/ui/web/rest/plugin/PluginInstanceControllerDefinition.scala

@@ -1,74 +1,78 @@
 package org.codeoverflow.chatoverflow.ui.web.rest.plugin
 
 import org.codeoverflow.chatoverflow.ui.web.rest.DTOs._
+import org.codeoverflow.chatoverflow.ui.web.rest.TagSupport
 import org.scalatra.swagger.SwaggerSupport
 import org.scalatra.swagger.SwaggerSupportSyntax.OperationBuilder
 
-trait PluginInstanceControllerDefinition extends SwaggerSupport {
+trait PluginInstanceControllerDefinition extends SwaggerSupport with TagSupport {
 
   val getInstances: OperationBuilder =
     (apiOperation[List[PluginInstance]]("getInstances")
       summary "Shows all plugin instances."
-      description "Shows the name, plugin information and requirement keys of all plugin instances.")
-
+      description "Shows the name, plugin information and requirement keys of all plugin instances."
+      tags controllerTag)
   val getInstance: OperationBuilder =
     (apiOperation[PluginInstance]("getInstance")
       summary "Shows a plugin instance."
       description "Shows the name, plugin information and requirement keys of a specified plugin instance."
+      tags controllerTag
       parameter pathParam[String]("instanceName").description("The name of the plugin instance."))
-
   val getRequirements: OperationBuilder =
     (apiOperation[List[Requirement]]("getRequirements")
       summary "Shows all requirements of a plugin instance."
       description "Shows state, name and type of all requirements of a specified plugin instance."
+      tags controllerTag
       parameter pathParam[String]("instanceName").description("The name of the plugin instance."))
-
   val getRequirement: OperationBuilder =
     (apiOperation[Requirement]("getRequirement")
       summary "Shows a specific requirement of a plugin instance."
       description "Shows state, name and type of one specific requirement of a specified plugin instance."
+      tags controllerTag
       parameter pathParam[String]("instanceName").description("The name of the plugin instance.")
       parameter pathParam[String]("requirementID").description("The unique id of the requirement."))
-
   val putRequirement: OperationBuilder =
     (apiOperation[ResultMessage]("putRequirement")
       summary "Changes the value and type of a specific requirement."
       description "Changes the value (serialized content) and the target type of a requirement of one instance."
+      tags controllerTag
       parameter pathParam[String]("instanceName").description("The name of the plugin instance.")
       parameter pathParam[String]("requirementID").description("The unique id of the requirement.")
       parameter bodyParam[RequirementInfo]("body").description("Requires target type and serialized content."))
-
   val getLog: OperationBuilder =
     (apiOperation[List[String]]("getLog")
       summary "Shows the log of a plugin instance."
       description "Shows all (or the newest) log messages of a specified plugin instance."
+      tags controllerTag
       parameter pathParam[String]("instanceName").description("The name of the plugin instance.")
       parameter queryParam[Option[String]]("startIndex").description("The start index of the message stream").optional)
-
   val postInstance: OperationBuilder =
     (apiOperation[ResultMessage]("postInstance")
       summary "Creates a new plugin instance."
       description "Creates a new plugin instance with given name and plugin type."
+      tags controllerTag
       parameter bodyParam[PluginInstanceRef]("body").description("Requires new instance name and PluginType (name and author)."))
-
   val deleteInstance: OperationBuilder =
     (apiOperation[PluginInstance]("deleteInstance")
       summary "Removes a plugin instance."
       description "Removes a plugin instance specified by its name, if possible."
+      tags controllerTag
       parameter pathParam[String]("instanceName").description("The name of the plugin instance."))
-
   val startInstance: OperationBuilder =
     (apiOperation[ResultMessage]("startInstance")
       summary "Starts a specific plugin instance."
       description "Starts a specific plugin instance if possible."
+      tags controllerTag
       parameter bodyParam[PluginInstanceName]("body").description("Requires the name of the plugin instance."))
-
   val stopInstance: OperationBuilder =
     (apiOperation[ResultMessage]("stopInstance")
       summary "Stops a specific plugin instance."
       description "Requires the stop of a specified plugin instance. This can take up to one loop interval."
+      tags controllerTag
       parameter bodyParam[PluginInstanceName]("body").description("Requires the name of the plugin instance."))
 
+  override def controllerTag: String = "instance"
+
   override protected def applicationDescription: String = "Handles plugin instances and requirements."
 
 }

src/main/scala/org/codeoverflow/chatoverflow/ui/web/rest/types/TypesControllerDefinition.scala

@@ -1,43 +1,46 @@
 package org.codeoverflow.chatoverflow.ui.web.rest.types
 
 import org.codeoverflow.chatoverflow.ui.web.rest.DTOs._
+import org.codeoverflow.chatoverflow.ui.web.rest.TagSupport
 import org.scalatra.swagger.SwaggerSupport
 import org.scalatra.swagger.SwaggerSupportSyntax.OperationBuilder
 
-trait TypesControllerDefinition extends SwaggerSupport {
+trait TypesControllerDefinition extends SwaggerSupport with TagSupport {
 
   val getPluginType: OperationBuilder =
     (apiOperation[List[PluginType]]("getPlugin")
       summary "Shows all possible plugin types."
-      description "Shows name, author, api version and state of all possible plugin types.")
-
+      description "Shows name, author, api version and state of all possible plugin types."
+      tags controllerTag)
   val getRequirementType: OperationBuilder =
     (apiOperation[RequirementTypes]("getRequirementType")
       summary "Shows all possible requirement types."
-      description "Shows the fully qualified api type strings of all requirement types, grouped by input/output/parameter.")
-
+      description "Shows the fully qualified api type strings of all requirement types, grouped by input/output/parameter."
+      tags controllerTag)
   val getConnectorType: OperationBuilder =
     (apiOperation[List[String]]("getConnectorType")
       summary "Shows all possible connector types."
-      description "Shows the fully qualified type strings of all connectors.")
-
+      description "Shows the fully qualified type strings of all connectors."
+      tags controllerTag)
   val getTypes: OperationBuilder =
     (apiOperation[Types]("getTypes")
       summary "Shows all possible types of plugins, requirements and connectors."
-      description "Shows all possible types of plugins, requirements and connectors.")
-
+      description "Shows all possible types of plugins, requirements and connectors."
+      tags controllerTag)
   val getReqImpl: OperationBuilder =
     (apiOperation[APIAndSpecificType]("getReqImpl")
       summary "Shows all implementations of a specified api type."
       description "Shows the specific type (implementation) and the connector of a specified api type."
+      tags controllerTag
       parameter queryParam[String]("api").description("The fully qualified api type string"))
-
   val getSubTypes: OperationBuilder =
     (apiOperation[SubTypes]("getSubTypes")
       summary "Shows all sub types of a specified api type."
       description "Shows all sub types (sub typing api interfaces) of a specified api type."
+      tags controllerTag
       parameter queryParam[String]("api").description("The fully qualified api type string"))
 
+  override def controllerTag: String = "type"
 
   override protected def applicationDescription: String = "Handles requirement, plugin and controller types."