Merge branch 'master' into ZNTA-845-findbugs

api/zanata-common-api/README.md

@@ -0,0 +1,7 @@
+To build API docs locally, run
+
+    mvn site -pl :zanata-common-api
+
+To open the file you can use
+
+    google-chrome target/site/rest-api-docs/index.html

api/zanata-common-api/etc/enunciate/enunciate.xml

@@ -1,14 +1,7 @@
 <enunciate
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.6.0.xsd">
-  <namespaces>
-    <namespace id="zanata" uri="http://www.zanata.org" />
-  </namespaces>
-  <api-classes>
-    <include pattern="org.zanata.rest.*" />
-  </api-classes>
+  xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.9.0.xsd">
   <title>Zanata REST API</title>
-  <copyright>Red Hat, Inc and others</copyright>
   <description>
     <![CDATA[
       <h1>Introduction</h1>
@@ -22,19 +15,44 @@
 
         Some of the available resources require authentication and will respond with
         an UNAUTHORIZED (401) code if not available. To prevent this, you must supply
-        credentials in the form of the "X-Auth-User" header, which should contain a
-        valid Zanata user name, and "X-Auth-Token", which should contain the
-        corresponding API key for the user. Additionally, the service might continue
+        credentials in the form of HTTP headers as indicated in the table below.
+        Additionally, the service might continue
         to respond with the same code if the authenticated user does not have
         the right permissions to access the resource.
+
+        <table class='table table-hover resources'>
+          <thead>
+            <tr>
+              <th align="center">Header</th>
+              <th align="center">Description</th>
+            </tr>
+          </thead>
+          <tbody class='rowlink'>
+            <tr>
+              <td>X-Auth-User</td>
+              <td>User name</td>
+            </tr>
+            <tr>
+              <td>X-Auth-Token</td>
+              <td>User's API key</td>
+            </tr>
+          </tbody>
+        </table>
       </p>
     ]]>
   </description>
+  <copyright>Red Hat, Inc and others</copyright>
+  <!--<namespaces>-->
+    <!--<namespace id="zanata" uri="http://www.zanata.org" />-->
+  <!--</namespaces>-->
+  <!--<api-classes>-->
+  <!--<include pattern="org.zanata.rest.*" />-->
+  <!--</api-classes>-->
   <!-- https://github.com/stoicflame/enunciate/wiki/Modules -->
-  <!--<modules>-->
+  <modules>
     <!--<jaxb />-->
     <!--<jackson1 />-->
-    <!--<jaxrs />-->
+    <!--<jaxrs groupBy="path"/>-->
     <!--<docs />-->
-  <!--</modules>-->
+  </modules>
 </enunciate>

api/zanata-common-api/pom.xml

@@ -19,7 +19,7 @@
   </scm>
 
   <properties>
-    <enunciate.version>2.6.0</enunciate.version>
+    <enunciate.version>2.9.1</enunciate.version>
   </properties>
 
   <build>

api/zanata-common-api/src/main/java/org/zanata/rest/dto/Account.java

@@ -11,6 +11,8 @@
 import javax.xml.bind.annotation.XmlRootElement;
 import javax.xml.bind.annotation.XmlType;
 
+import com.webcohesion.enunciate.metadata.DocumentationExample;
+import com.webcohesion.enunciate.metadata.Label;
 import org.codehaus.jackson.annotate.JsonIgnoreProperties;
 import org.codehaus.jackson.annotate.JsonProperty;
 import org.codehaus.jackson.annotate.JsonPropertyOrder;
@@ -21,11 +23,15 @@
 import org.zanata.rest.MediaTypes;
 import org.zanata.rest.MediaTypes.Format;
 
+/**
+ * System user account.
+ */
 @XmlType(name = "accountType")
 @XmlRootElement(name = "account")
 @JsonIgnoreProperties(ignoreUnknown = true)
 @JsonPropertyOrder({ "email", "name", "username", "password" })
 @JsonSerialize(include = JsonSerialize.Inclusion.NON_NULL)
+@Label("Account")
 public class Account implements Serializable, HasMediaType {
 
     private String email;
@@ -58,6 +64,7 @@ public Account(String email, String name, String username,
     @XmlAttribute(name = "email", required = true)
     @Email
     @NotNull
+    @DocumentationExample("email@example.com")
     public String getEmail() {
         return email;
     }
@@ -68,6 +75,7 @@ public void setEmail(String email) {
 
     @XmlAttribute(name = "name", required = true)
     @NotEmpty
+    @DocumentationExample("Homer Simpson")
     public String getName() {
         return name;
     }
@@ -78,6 +86,7 @@ public void setName(String name) {
 
     @XmlAttribute(name = "username", required = true)
     @NotEmpty
+    @DocumentationExample("homer")
     public String getUsername() {
         return username;
     }
@@ -87,6 +96,7 @@ public void setUsername(String username) {
     }
 
     @XmlAttribute(name = "passwordHash")
+    @DocumentationExample("cf23df2207d99a74fbe169e3eba035e633b65d94")
     public String getPasswordHash() {
         return passwordHash;
     }
@@ -97,6 +107,7 @@ public void setPasswordHash(String password) {
 
     @XmlAttribute(name = "apiKey")
     @Size(min = 32, max = 32)
+    @DocumentationExample("qiyh4XPJGsOZ2MEAyLkfWqeQ")
     public String getApiKey() {
         return apiKey;
     }
@@ -117,6 +128,7 @@ public void setEnabled(boolean enabled) {
 
     @XmlElement(name = "role", namespace = Namespaces.ZANATA_OLD)
     @JsonProperty("roles")
+    @DocumentationExample(value = "admin", value2 = "project-creator")
     public Set<String> getRoles() {
         return roles;
     }
@@ -125,8 +137,12 @@ public void setRoles(Set<String> roles) {
         this.roles = roles;
     }
 
+    /**
+     * Global language teams the account belongs to
+     */
     @XmlElement(name = "tribe", namespace = Namespaces.ZANATA_OLD)
     @JsonProperty("tribes")
+    @DocumentationExample(value = "es", value2 = "ja")
     public Set<String> getTribes() {
         return tribes;
     }

api/zanata-common-api/src/main/java/org/zanata/rest/dto/ProcessStatus.java

@@ -29,6 +29,8 @@
 import javax.xml.bind.annotation.XmlRootElement;
 import javax.xml.bind.annotation.XmlType;
 
+import com.webcohesion.enunciate.metadata.DocumentationExample;
+import com.webcohesion.enunciate.metadata.Label;
 import org.codehaus.jackson.annotate.JsonProperty;
 
 /**
@@ -39,21 +41,28 @@
  */
 @XmlRootElement(name = "processStatus")
 @XmlType(name = "processStatusType")
+@Label("Process Status")
 public class ProcessStatus {
     @XmlEnum
+    @Label("Process Status Code")
     public enum ProcessStatusCode {
+        /** The process has not been accepted by the server */
         @XmlEnumValue("NotAccepted")
         NotAccepted,
 
+        /** The process has been accepted but is not yet running */
         @XmlEnumValue("Waiting")
         Waiting,
 
+        /** The process is being executed */
         @XmlEnumValue("Running")
         Running,
 
+        /** The process has finished normally */
         @XmlEnumValue("Finished")
         Finished,
 
+        /** The process has finshed with a failure */
         @XmlEnumValue("Failed")
         Failed,
     }
@@ -67,6 +76,7 @@ public enum ProcessStatusCode {
     private ProcessStatusCode statusCode;
 
     @XmlElement(required = true)
+    @DocumentationExample("http://zanata.example.com")
     public String getUrl() {
         return url;
     }
@@ -76,6 +86,7 @@ public void setUrl(String url) {
     }
 
     @XmlElement(required = true)
+    @DocumentationExample("55")
     public int getPercentageComplete() {
         return percentageComplete;
     }
@@ -87,6 +98,8 @@ public void setPercentageComplete(int percentageComplete) {
     @XmlElement(name = "message")
     @XmlElementWrapper(name = "messages", required = true)
     @JsonProperty("messages")
+    @DocumentationExample(value = "A warning message",
+            value2 = "A second warning message")
     public List<String> getMessages() {
         if (messages == null) {
             messages = new ArrayList<String>();

api/zanata-common-api/src/main/java/org/zanata/rest/dto/resource/AbstractResourceMeta.java

@@ -8,6 +8,7 @@
 import javax.xml.bind.annotation.XmlType;
 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
 
+import com.webcohesion.enunciate.metadata.Label;
 import org.codehaus.jackson.annotate.JsonIgnore;
 import org.codehaus.jackson.annotate.JsonProperty;
 import org.zanata.common.ContentType;
@@ -22,6 +23,7 @@
 
 @XmlType(name = "abstractResourceMetaType",
         propOrder = { "name", "extensions" })
+@Label("Abstract Resource")
 public abstract class AbstractResourceMeta implements Serializable,
         Extensible<AbstractResourceMetaExtension> {
     private static final long serialVersionUID = 1L;

api/zanata-common-api/src/main/java/org/zanata/rest/dto/resource/Resource.java

@@ -8,18 +8,23 @@
 import javax.xml.bind.annotation.XmlRootElement;
 import javax.xml.bind.annotation.XmlType;
 
+import com.webcohesion.enunciate.metadata.DocumentationExample;
+import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
 import org.codehaus.jackson.annotate.JsonIgnoreProperties;
 import org.codehaus.jackson.annotate.JsonProperty;
 import org.codehaus.jackson.annotate.JsonPropertyOrder;
 import org.codehaus.jackson.map.annotate.JsonSerialize;
 import org.zanata.common.Namespaces;
-import org.zanata.rest.dto.DTOUtil;
 
+/**
+ * A series of text flows to be translated and sharing common metadata.
+ */
 @XmlType(name = "resourceType", propOrder = { "textFlows" })
 @XmlRootElement(name = "resource")
 @JsonPropertyOrder({ "name", "contentType", "lang", "extensions", "textFlows" })
 @JsonIgnoreProperties(ignoreUnknown = true)
 @JsonSerialize(include = JsonSerialize.Inclusion.NON_NULL)
+@ResourceLabel("Resource")
 public class Resource extends AbstractResourceMeta {
 
     private static final long serialVersionUID = 1L;
@@ -32,6 +37,9 @@ public Resource(String name) {
         super(name);
     }
 
+    /**
+     * Set of text flows containing the translatable strings.
+     */
     @XmlElementWrapper(name = "text-flows", required = false,
             namespace = Namespaces.ZANATA_OLD)
     @XmlElement(name = "text-flow",

api/zanata-common-api/src/main/java/org/zanata/rest/dto/resource/TextContainer.java

@@ -30,6 +30,8 @@
 import javax.xml.bind.annotation.XmlElementWrapper;
 import javax.xml.bind.annotation.XmlTransient;
 
+import com.webcohesion.enunciate.metadata.DocumentationExample;
+import com.webcohesion.enunciate.metadata.Label;
 import org.codehaus.jackson.annotate.JsonIgnore;
 import org.codehaus.jackson.annotate.JsonProperty;
 import org.zanata.common.HasContents;
@@ -47,6 +49,7 @@
  *         href="mailto:sflaniga@redhat.com">sflaniga@redhat.com</a>
  */
 @XmlTransient
+@Label("Text Container")
 class TextContainer implements Serializable, HasContents {
     private static final long serialVersionUID = 1L;
 
@@ -60,6 +63,7 @@ class TextContainer implements Serializable, HasContents {
     @XmlElement(name = "content", required = false,
             namespace = Namespaces.ZANATA_OLD)
     @JsonProperty("content")
+    @DocumentationExample(exclude = true)
     private String content;
 
     /**
@@ -71,6 +75,8 @@ class TextContainer implements Serializable, HasContents {
     @XmlElementWrapper(name = "contents", namespace = Namespaces.ZANATA_OLD)
     @XmlElement(name = "content", namespace = Namespaces.ZANATA_OLD)
     @JsonProperty("contents")
+    @DocumentationExample(value = "An english string to translate",
+        value2 = "A plural english string to translate")
     private List<String> contents;
 
     /**

api/zanata-common-api/src/main/java/org/zanata/rest/dto/resource/TextFlow.java

@@ -11,6 +11,8 @@
 import javax.xml.bind.annotation.XmlType;
 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
 
+import com.webcohesion.enunciate.metadata.DocumentationExample;
+import com.webcohesion.enunciate.metadata.Label;
 import org.codehaus.jackson.annotate.JsonIgnore;
 import org.codehaus.jackson.annotate.JsonIgnoreProperties;
 import org.codehaus.jackson.annotate.JsonPropertyOrder;
@@ -23,12 +25,16 @@
 import org.zanata.rest.dto.LocaleIdAdapter;
 import org.zanata.rest.dto.extensions.gettext.TextFlowExtension;
 
+/**
+ * A translatable string
+ */
 @XmlType(name = "textFlowType", propOrder = { "content", "contents", "plural",
         "extensions" })
 @JsonPropertyOrder({ "id", "lang", "content", "contents", "plural",
         "extensions" })
 @JsonIgnoreProperties(ignoreUnknown = true)
 @JsonSerialize(include = JsonSerialize.Inclusion.NON_NULL)
+@Label("Text Flow")
 public class TextFlow extends TextContainer implements
         Extensible<TextFlowExtension>, Serializable {
     private static final long serialVersionUID = 1L;
@@ -88,6 +94,7 @@ public TextFlow(String id, LocaleId lang, List<String> contentList) {
     }
 
     @XmlAttribute(name = "id", required = true)
+    @DocumentationExample("abc123")
     public String getId() {
         return id;
     }
@@ -97,7 +104,7 @@ public void setId(String id) {
     }
 
     /**
-     * @return whether this message supports plurals
+     * Whether this message supports plurals
      */
     @XmlElement(namespace = Namespaces.ZANATA_OLD)
     public boolean isPlural() {
@@ -112,8 +119,12 @@ public void setPlural(boolean pluralSupported) {
         this.plural = pluralSupported;
     }
 
+    /**
+     * Locale code for this text flow.
+     */
     @XmlJavaTypeAdapter(type = LocaleId.class, value = LocaleIdAdapter.class)
     @XmlAttribute(name = "lang", namespace = Namespaces.XML, required = false)
+    @DocumentationExample("es-ES")
     public LocaleId getLang() {
         return lang;
     }