Update webhook helper section

Signed-off-by: Jackline Mutua <[email protected]>

api/openapi-spec/conventions-server.yaml

@@ -11,15 +11,23 @@ paths:
   /webhook:
     post:
       description: "a sample conventions server"
+      parameters: 
+          in: body
+          schema: 
+              "$ref": "#/components/schemas/PodConventionContext'"
+      requestBody:
+        description: |
+          Contains data required to allow the conventions controller to be able to apply a 
+          set of defined conventions.
+        required: true
       responses:
         200:
           description: Successfully applied defined conventions
-          content:
-            "application/json":
-              schema:
-                $ref: '#/components/schemas/PodConventionContext'
+          application/json':
+            schema:
+              $ref: '#/components/schemas/PodTemplateSpec'
         400:
-          description: Error decoding PodConventionContext from the request body or request body is nil 
+          description: Return error if unable to decode request body into a PodConventionContext type or if request body is nil 
         500:
           description: Internal server error
           content:
@@ -31,7 +39,7 @@ components:
     PodConventionContext: 
       type: object
       properties:
-        apiVersions: 
+        apiVersion: 
           type: string
         kind: 
           type: string
@@ -80,7 +88,7 @@ components:
           example: "example.com/repository/nginx:alpine"
         BOMs:
           type: array
-          description: "an array of bill of matearials (BOMs)"
+          description: "an array of Bills of Materials (BOMs) describing the software components and their dependencies."
           items:
             $ref: "#/components/schemas/BOM"
         config: 
@@ -90,9 +98,10 @@ components:
       type: object 
       properties:
         name: 
+          description: "bom-name"
           type: string 
         raw: 
-          description: a base64 encoded string  
+          description: "a byte array with the encoded content of the BOM"
           type: string
     PodConventionContextStatus:
       type: object 

docs/design.md

@@ -240,18 +240,15 @@ In the future other mechanisms may be defined to provide conventions other than
 
 #### Webhook Helper Library  
 
-In order for the conventions controller to apply a set of conventions, it requires these conventions to be authored in the form of a webhook. 
+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.
 
-The authored webhook is registered as follows:
-  ```
-  http.HandleFunc(< path >, webhook.ConventionHandler(ctx, conventions_name))
-  ```
-  The convention controller handler function expects a `context Context` and a function describing conventions to be applied. See [springboot-convetions example](../samples/spring-convention-server/server.go)
+_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 `Handler` is called from the controller in priority order as defined by the `ClusterPodConvention`. 
-  The Open API Specification for the webhook is documented [here](/api/openapi-spec/conventions-server.yaml) 
+  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`. 
 
 ## Lifecycle