Update descriptions and add examples

Signed-off-by: Jackline Mutua <jmutua@vmware.com>

api/openapi-spec/conventions-server.yaml

@@ -1,19 +1,19 @@
 openapi: 3.0.0
 info:
   title: Conventions server 
-  description: a sample conventions server
+  description: a sample conventions server.
   version: 1.0.0
   license:
     name: Apache-2.0
     url: "https://www.apache.org/licenses/LICENSE-2.0.html"
 paths:
   /webhook:
     post:
-      description: a sample conventions server
+      description: a sample conventions server.
       requestBody:
         description: |
-          Contains data required to allow the conventions controller to be able to apply a 
-          set of defined conventions.
+          The PodConventionContext as defined in the API object webhooks.conventions.apps.tanzu.vmware.com API group 
+          is the structure used for both request and response from the convention server.
         content:
            "application/json":
               schema: 
@@ -26,7 +26,7 @@ paths:
               schema:
                $ref: "#/components/schemas/PodConventionContext"
         400:
-          description: Return error if unable to decode request body into a PodConventionContext type or if request body is nil 
+          description: Return error if unable to decode request body into a PodConventionContext type or if request body is nil. 
           content:
             "application/json":
               schema:
@@ -40,9 +40,9 @@ paths:
 components:
   schemas:
     PodConventionContext:
-      description: a wrapper for the PodConventionContextSpec and the PodConventionContextStatus
+      description: a wrapper for the PodConventionContextSpec and the PodConventionContextStatus.
       type: object
-      properteies:
+      properties:
         apiVersion: 
           type: string
         kind: 
@@ -58,21 +58,24 @@ components:
           $ref: "#/components/schemas/PodConventionContextStatus"
     PodConventionContextSpec:
       type: object
-      description: a wrapper of the PodTemplateSpec and the ImageConfig provided in the request body of the server
+      description: a wrapper of the PodTemplateSpec and the ImageConfig provided in the request body of the server.
       properties:
         template:
           $ref: "#/components/schemas/PodTemplateSpec"
         imageConfig:
           type: array 
-          description: an array of imageConfig objects with each image configuration object holding the name of the image, the BOM, and the OCI image configuration with image metadata from the repository.
+          description: |
+            an array of imageConfig objects with each image configuration object holding the name of the image, the BOM, and the OCI image
+            configuration with image metadata from the repository. Each of the image config array entries have a 1:1 mapping to 
+            images referenced in the PodTemplateSpec. 
           items:
             $ref: "#/components/schemas/ImageConfig"
     PodTemplateSpec:
       type: object 
       properties:
         spec: 
           type: object
-          description: defines the PodTemplateSpec to be enriched by conventions
+          description: defines the PodTemplateSpec to be enriched by conventions.
         metadata:
           type: object
           properties:
@@ -89,36 +92,53 @@ components:
       properties: 
         image: 
           type: string 
-          description: a string reference to the image name and tag or associated digest
+          description: a string reference to the image name and tag or associated digest.
           example: "example.com/repository/nginx:alpine"
         BOMs:
           type: array
-          description: an array of Bills of Materials (BOMs) describing the software components and their dependencies.
+          description: | 
+            an array of Bills of Materials (BOMs) describing the software components and their dependencies and may be zero or more per image.
           items:
             $ref: "#/components/schemas/BOM"
+          example: | 
+            "boms": [{
+                "name": "bom-name",
+                "raw": "a byte array"
+            }],
         config: 
           type: object 
-          description: a ggcrv1 config file object
+          description: a ggcrv1 config file object.
     BOM: 
       type: object 
       properties:
         name: 
           description: bom-name
           type: string 
         raw: 
-          description: a byte array with the encoded content of the BOM
+          description: a byte array with the encoded content of the BOM.
           type: string
+      example: | 
+        {
+          "name": "bom-name",
+          "raw": "some byte array"
+        }
     PodConventionContextStatus:
-      description: status type used to represent the current status of the context retrieved by the request
+      description: status type used to represent the current status of the context retrieved by the request.
       type: object 
       properties:
         template: 
           $ref: "#/components/schemas/PodTemplateSpec"
         appliedConventions:
-          description: a string array of conventions to be applied 
+          description: list of names of conventions applied
           type: array 
           items:
-            type: string        
+            type: string
+          example: |
+              "appliedConventions": [ 
+                "convention-1", 
+                "convention-2",
+                "convention-4" 
+              ]        
     Error:
       type: object
       properties:

docs/design.md

@@ -240,15 +240,15 @@ In the future other mechanisms may be defined to provide conventions other than
 
 #### Webhook Helper Library  
 
-A conventions author can provide a set of conventions to the conventions controller in various ways. One way to do this, is by creating a webhook which can be written in any programming language. See the [Open API Specification](/api/openapi-spec/conventions-server.yaml) that defines how to to create your own conventions server.
+A conventions author can provide a set of conventions to the conventions controller in various ways. One way to do this, is by creating a webhook which can be written in any programming language. See the [Open API Specification](/api/openapi-spec/conventions-server.yaml) that defines how to to create your own conventions server. Applied conventions defined in the conventions server implementation created by a conventions author need to be defined as pure functions.
 
 _Go Spring Boot example_
 
 In the`go` [springboot conventions example](/samples/spring-convention-server/) implementation provided in the `/samples` directory, the author has defined a set of conventions to be applied to a spring boot application using a webhook which is registered as follows:-   
   ```
   http.HandleFunc("/", webhook.ConventionHandler(ctx, addSpringBootConventions))
   ```
-  The convention controller handler function expects a `context Context` and a function describing conventions to be applied. The `Handler` is called from the controller in priority order as defined by the `ClusterPodConvention`. 
+  The convention controller handler function expects a `context Context` and applied conventions which are provided as a function called `addSpringBootConventions`. This function defines conventions to be applied to any springboot application.
 
 ## Lifecycle