Add descriptions for types

Author: russgold

docs/domains/Domain.json

@@ -1,8 +1,10 @@
 {
   "$schema": "http://json-schema.org/draft-04/schema#",
+  "description": "Domain represents a WebLogic domain and how it will be realized in the Kubernetes cluster.",
   "type": "object",
   "definitions": {
     "AdminServer": {
+      "description": "AdminServer represents the operator configuration for the admin server.",
       "type": "object",
       "properties": {
         "serverStartState": {
@@ -53,10 +55,11 @@
       }
     },
     "Channel": {
+      "description": "Describes a single channel used by the admin server.",
       "type": "object",
       "properties": {
         "channelName": {
-          "description": "Name of channel.\ndefault\u0027 refers to the admin server\u0027s default channel (configured via the ServerMBean\u0027s ListenPort) \n\u0027default-secure\u0027 refers to the admin server\u0027s default secure channel (configured via the ServerMBean\u0027s SSLMBean\u0027s ListenPort) \n\u0027default-admin\u0027 refers to the admin server\u0027s default administrative channel (configured via the DomainMBean\u0027s AdministrationPort) \nOtherwise, the name is the name of one of the admin server\u0027s network access points (configured via the ServerMBean\u0027s NetworkAccessMBeans).",
+          "description": "Name of channel.\n\u0027default\u0027 refers to the admin server\u0027s default channel (configured via the ServerMBean\u0027s ListenPort) \n\u0027default-secure\u0027 refers to the admin server\u0027s default secure channel (configured via the ServerMBean\u0027s SSLMBean\u0027s ListenPort) \n\u0027default-admin\u0027 refers to the admin server\u0027s default administrative channel (configured via the DomainMBean\u0027s AdministrationPort) \nOtherwise, the name is the name of one of the admin server\u0027s network access points (configured via the ServerMBean\u0027s NetworkAccessMBeans).",
           "type": "string"
         },
         "nodePort": {
@@ -69,6 +72,7 @@
       ]
     },
     "Cluster": {
+      "description": "An element representing a cluster in the domain configuration.",
       "type": "object",
       "properties": {
         "serverStartState": {
@@ -156,6 +160,7 @@
       }
     },
     "DomainSpec": {
+      "description": "DomainSpec is a description of a domain.",
       "type": "object",
       "properties": {
         "serverStartState": {
@@ -273,6 +278,7 @@
       }
     },
     "DomainStatus": {
+      "description": "DomainStatus represents information about the status of a domain. Status may trail the actual state of a system.",
       "type": "object",
       "properties": {
         "reason": {
@@ -322,6 +328,7 @@
       }
     },
     "ManagedServer": {
+      "description": "ManagedServer represents the operator configuration for a single managed server.",
       "type": "object",
       "properties": {
         "serverStartState": {
@@ -404,6 +411,7 @@
       }
     },
     "ServerPod": {
+      "description": "ServerPod describes the configuration for a Kubernetes pod for a server.",
       "type": "object",
       "properties": {
         "livenessProbe": {

docs/domains/Domain.md

@@ -1,5 +1,6 @@
 ### Domain
 
+Domain represents a WebLogic domain and how it will be realized in the Kubernetes cluster.
 | Name | Type | Description |
 | --- | --- | --- |
 | apiVersion | string | The API version for the Domain. Must be 'weblogic.oracle/v2'. |
@@ -10,6 +11,7 @@
 
 ### Domain Spec
 
+DomainSpec is a description of a domain.
 | Name | Type | Description |
 | --- | --- | --- |
 | adminServer | [Admin Server](#admin-server) | Configuration for the admin server. |
@@ -36,6 +38,7 @@
 
 ### Domain Status
 
+DomainStatus represents information about the status of a domain. Status may trail the actual state of a system.
 | Name | Type | Description |
 | --- | --- | --- |
 | conditions | array of [Domain Condition](#domain-condition) | Current service state of domain. |
@@ -47,6 +50,7 @@
 
 ### Admin Server
 
+AdminServer represents the operator configuration for the admin server.
 | Name | Type | Description |
 | --- | --- | --- |
 | adminService | [Admin Service](#admin-service) | Configures which of the admin server's WebLogic admin channels should be exposed outside the Kubernetes cluster via a node port service. |
@@ -58,6 +62,7 @@
 
 ### Cluster
 
+An element representing a cluster in the domain configuration.
 | Name | Type | Description |
 | --- | --- | --- |
 | clusterName | string | The name of this cluster. Required |
@@ -72,6 +77,7 @@
 
 ### Managed Server
 
+ManagedServer represents the operator configuration for a single managed server.
 | Name | Type | Description |
 | --- | --- | --- |
 | restartVersion | string | If present, every time this value is updated the operator will restart the required servers. |
@@ -83,6 +89,7 @@
 
 ### Server Pod
 
+ServerPod describes the configuration for a Kubernetes pod for a server.
 | Name | Type | Description |
 | --- | --- | --- |
 | annotations |  | The annotations to be attached to generated resources. |
@@ -159,9 +166,10 @@
 
 ### Channel
 
+Describes a single channel used by the admin server.
 | Name | Type | Description |
 | --- | --- | --- |
-| channelName | string | Name of channel.<br/>default' refers to the admin server's default channel (configured via the ServerMBean's ListenPort) <br/>'default-secure' refers to the admin server's default secure channel (configured via the ServerMBean's SSLMBean's ListenPort) <br/>'default-admin' refers to the admin server's default administrative channel (configured via the DomainMBean's AdministrationPort) <br/>Otherwise, the name is the name of one of the admin server's network access points (configured via the ServerMBean's NetworkAccessMBeans). |
+| channelName | string | Name of channel.<br/>'default' refers to the admin server's default channel (configured via the ServerMBean's ListenPort) <br/>'default-secure' refers to the admin server's default secure channel (configured via the ServerMBean's SSLMBean's ListenPort) <br/>'default-admin' refers to the admin server's default administrative channel (configured via the DomainMBean's AdministrationPort) <br/>Otherwise, the name is the name of one of the admin server's network access points (configured via the ServerMBean's NetworkAccessMBeans). |
 | nodePort | number | Specifies the port number used to access the WebLogic channel outside of the Kubernetes cluster. If not specified, defaults to the port defined by the WebLogic channel. |
 
 ### Subsystem Health

docs/domains/index.html

@@ -924,6 +924,7 @@
       "properties": {}
     },
     "AdminServer": {
+      "description": "AdminServer represents the operator configuration for the admin server.",
       "type": "object",
       "properties": {
         "serverStartState": {
@@ -974,10 +975,11 @@
       }
     },
     "Channel": {
+      "description": "Describes a single channel used by the admin server.",
       "type": "object",
       "properties": {
         "channelName": {
-          "description": "Name of channel.\ndefault\u0027 refers to the admin server\u0027s default channel (configured via the ServerMBean\u0027s ListenPort) \n\u0027default-secure\u0027 refers to the admin server\u0027s default secure channel (configured via the ServerMBean\u0027s SSLMBean\u0027s ListenPort) \n\u0027default-admin\u0027 refers to the admin server\u0027s default administrative channel (configured via the DomainMBean\u0027s AdministrationPort) \nOtherwise, the name is the name of one of the admin server\u0027s network access points (configured via the ServerMBean\u0027s NetworkAccessMBeans).",
+          "description": "Name of channel.\n\u0027default\u0027 refers to the admin server\u0027s default channel (configured via the ServerMBean\u0027s ListenPort) \n\u0027default-secure\u0027 refers to the admin server\u0027s default secure channel (configured via the ServerMBean\u0027s SSLMBean\u0027s ListenPort) \n\u0027default-admin\u0027 refers to the admin server\u0027s default administrative channel (configured via the DomainMBean\u0027s AdministrationPort) \nOtherwise, the name is the name of one of the admin server\u0027s network access points (configured via the ServerMBean\u0027s NetworkAccessMBeans).",
           "type": "string"
         },
         "nodePort": {
@@ -990,6 +992,7 @@
       ]
     },
     "Cluster": {
+      "description": "An element representing a cluster in the domain configuration.",
       "type": "object",
       "properties": {
         "serverStartState": {
@@ -1077,6 +1080,7 @@
       }
     },
     "DomainSpec": {
+      "description": "DomainSpec is a description of a domain.",
       "type": "object",
       "properties": {
         "serverStartState": {
@@ -1194,6 +1198,7 @@
       }
     },
     "DomainStatus": {
+      "description": "DomainStatus represents information about the status of a domain. Status may trail the actual state of a system.",
       "type": "object",
       "properties": {
         "reason": {
@@ -1243,6 +1248,7 @@
       }
     },
     "ManagedServer": {
+      "description": "ManagedServer represents the operator configuration for a single managed server.",
       "type": "object",
       "properties": {
         "serverStartState": {
@@ -1325,6 +1331,7 @@
       }
     },
     "ServerPod": {
+      "description": "ServerPod describes the configuration for a Kubernetes pod for a server.",
       "type": "object",
       "properties": {
         "livenessProbe": {

docs/domains/k8s1.9.0.md

@@ -5,6 +5,7 @@
 
 ### Object Meta
 
+ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.
 | Name | Type | Description |
 | --- | --- | --- |
 | annotations |  | Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations |
@@ -26,19 +27,22 @@
 
 ### Local Object Reference
 
+LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace.
 | Name | Type | Description |
 | --- | --- | --- |
 | name | string | Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names |
 
 ### Secret Reference
 
+SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace
 | Name | Type | Description |
 | --- | --- | --- |
 | name | string | Name is unique within a namespace to reference a secret resource. |
 | namespace | string | Namespace defines the space within which the secret name must be unique. |
 
 ### Security Context
 
+SecurityContext holds security configuration that will be applied to a container. Some fields are present in both SecurityContext and PodSecurityContext.  When both are set, the values in SecurityContext take precedence.
 | Name | Type | Description |
 | --- | --- | --- |
 | allowPrivilegeEscalation | boolean | AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN |
@@ -51,6 +55,7 @@
 
 ### Env Var
 
+EnvVar represents an environment variable present in a Container.
 | Name | Type | Description |
 | --- | --- | --- |
 | name | string | Name of the environment variable. Must be a C_IDENTIFIER. |
@@ -59,6 +64,7 @@
 
 ### Pod Security Context
 
+PodSecurityContext holds pod-level security attributes and common container settings. Some fields are also present in container.securityContext.  Field values of container.securityContext take precedence over field values of PodSecurityContext.
 | Name | Type | Description |
 | --- | --- | --- |
 | fsGroup |  | A special supplemental group that applies to all containers in a pod. Some volume types allow the Kubelet to change the ownership of that volume to be owned by the pod:<br/><br/>1. The owning GID will be the FSGroup 2. The setgid bit is set (new files created in the volume will be owned by FSGroup) 3. The permission bits are OR'd with rw-rw----<br/><br/>If unset, the Kubelet will not modify the ownership and permissions of any volume. |
@@ -69,13 +75,15 @@
 
 ### Resource Requirements
 
+ResourceRequirements describes the compute resource requirements.
 | Name | Type | Description |
 | --- | --- | --- |
 | limits |  | Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ |
 | requests |  | Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ |
 
 ### Volume Mount
 
+VolumeMount describes a mounting of a Volume within a container.
 | Name | Type | Description |
 | --- | --- | --- |
 | mountPath | string | Path within the container at which the volume should be mounted.  Must not contain ':'. |
@@ -86,6 +94,7 @@
 
 ### Volume
 
+Volume represents a named volume in a pod that may be accessed by any container in the pod.
 | Name | Type | Description |
 | --- | --- | --- |
 | awsElasticBlockStore | [AWS Elastic Block Store Volume Source](#aws-elastic-block-store-volume-source) | AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore |

json-schema/src/main/java/oracle/kubernetes/json/Description.java

@@ -5,14 +5,15 @@
 package oracle.kubernetes.json;
 
 import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.TYPE;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /** Supplies a description for a field to be inserted into the generated JSON schema. */
 @Retention(RetentionPolicy.RUNTIME)
-@Target(FIELD)
+@Target({TYPE, FIELD})
 public @interface Description {
   String value();
 }

json-schema/src/main/java/oracle/kubernetes/json/SchemaGenerator.java

@@ -15,7 +15,17 @@
 import java.lang.reflect.Method;
 import java.lang.reflect.Modifier;
 import java.net.URL;
-import java.util.*;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import java.util.TreeMap;
 import javax.annotation.Nonnull;
 import org.joda.time.DateTime;
 
@@ -398,6 +408,7 @@ private void generateObjectTypeIn(Map<String, Object> result, Class<?> type) {
       List<String> requiredFields = new ArrayList<>();
       result.put("type", "object");
       if (includeAdditionalProperties) result.put("additionalProperties", "false");
+      Optional.ofNullable(getDescription(type)).ifPresent(s -> result.put("description", s));
       result.put("properties", properties);
 
       for (Field field : getPropertyFields(type)) {
@@ -411,6 +422,11 @@ private void generateObjectTypeIn(Map<String, Object> result, Class<?> type) {
     }
   }
 
+  private String getDescription(Class<?> aClass) {
+    Description description = aClass.getAnnotation(Description.class);
+    return description != null ? description.value() : null;
+  }
+
   private Collection<Field> getPropertyFields(Class<?> type) {
     Set<Field> result = new HashSet<>();
     for (Class<?> cl = type; cl != null && !cl.equals(Object.class); cl = cl.getSuperclass())

json-schema/src/main/java/oracle/kubernetes/json/YamlDocGenerator.java

@@ -36,13 +36,19 @@ public String generate(String schemaName) {
   public String generate(String reference, Map<String, Object> schema) {
     referencesNeeded.remove(reference);
     StringBuilder sb = new StringBuilder("### ");
-    sb.append(toStructureName(reference)).append("\n\n").append(generateForClass(schema));
+    sb.append(toStructureName(reference)).append("\n\n");
+    Optional.ofNullable(getDescription(schema)).ifPresent(s -> sb.append(s).append("\n"));
+    sb.append(generateForClass(schema));
     while (!referencesNeeded.isEmpty()) {
       generateForDefinition(sb, referencesNeeded.get(0));
     }
     return sb.toString();
   }
 
+  private String getDescription(Map<String, Object> schema) {
+    return (String) schema.get("description");
+  }
+
   private void generateForDefinition(StringBuilder sb, String reference) {
     Map<String, Object> definitions = subMap(schema, "definitions");
     Map<String, Object> definition = subMap(definitions, reference);

json-schema/src/test/java/oracle/kubernetes/json/DerivedObject.java

@@ -5,6 +5,7 @@
 package oracle.kubernetes.json;
 
 @SuppressWarnings("unused")
+@Description("A simple object used for testing")
 class DerivedObject extends SimpleObject {
   @Description("An int\nvalue")
   private int anInt;

json-schema/src/test/java/oracle/kubernetes/json/SchemaGeneratorTest.java

@@ -250,6 +250,7 @@ public void whenAdditionalPropertiesDisabled_doNotGenerateTheProperty() {
   public void generateSchemaForDerivedObject() {
     Object schema = generator.generate(DerivedObject.class);
 
+    assertThat(schema, hasJsonPath("$.description", equalTo("A simple object used for testing")));
     assertThat(schema, hasJsonPath("$.type", equalTo("object")));
     assertThat(schema, hasJsonPath("$.additionalProperties", equalTo("false")));
     assertThat(schema, hasJsonPath("$.properties.aBoolean.type", equalTo("boolean")));

json-schema/src/test/java/oracle/kubernetes/json/YamlDocGeneratorTest.java

@@ -179,6 +179,7 @@ public void generateMarkdownWithReferencedSections() {
                 "",
                 "### Derived Object",
                 "",
+                "A simple object used for testing",
                 tableHeader(),
                 tableEntry("aBoolean", "boolean", "A flag"),
                 tableEntry("anInt", "number", "An int<br/>value"))));
@@ -247,6 +248,7 @@ public void whenExternalSchemaSpecified_generateMarkdownForIt() throws IOExcepti
                 "\n",
                 "### Env Var",
                 "",
+                "EnvVar represents an environment variable present in a Container.",
                 tableHeader(),
                 tableEntry(
                     "name",