Update webhook helper section

Signed-off-by: Jackline Mutua <[email protected]>
vmware-tanzu · Apr 18, 2022 · e441912 · e441912
1 parent 1815ab6
commit e441912
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 23 deletions.
diff --git a/api/openapi-spec/conventions-server.yaml b/api/openapi-spec/conventions-server.yaml
@@ -1,37 +1,48 @@
 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'
+    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.
+        content:
+           "application/json":
+              schema: 
+               $ref: "#/components/schemas/PodConventionContext"
       responses:
         200:
           description: Successfully applied defined conventions
-          content:
+          content: 
             "application/json":
               schema:
-                $ref: '#/components/schemas/PodConventionContext'
+               $ref: "#/components/schemas/PodConventionContext"
         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 
+          content:
+            "application/json":
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
         500:
           description: Internal server error
           content:
             "application/json":
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"
 components:
   schemas:
     PodConventionContext: 
       type: object
       properties:
-        apiVersions: 
+        apiVersion: 
           type: string
         kind: 
           type: string
@@ -46,20 +57,21 @@ 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
       properties:
         template:
           $ref: "#/components/schemas/PodTemplateSpec"
         imageConfig:
           type: array 
-          description: an array of imageConfig objects
+          description: an array of imageConfig objects with image configuration object holding the name of the image, the BOM, and the OCI image configuration with image metadata from the repository.
           items:
             $ref: "#/components/schemas/ImageConfig"
     PodTemplateSpec:
       type: object 
       properties:
         spec: 
           type: object
-          description: specification of the desired behavior of a pod
+          description: defines the PodTemplateSpec to be enriched by conventions
         metadata:
           type: object
           properties:
@@ -80,21 +92,23 @@ 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: 
           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 base64 encoded string  
+          description: a byte array with the encoded content of the BOM
           type: string
     PodConventionContextStatus:
+      description: status type used to represent the current status of the context retrieved by the request
       type: object 
       properties:
         template: 
@@ -109,4 +123,10 @@ components:
       properties:
         message:
           type: string
-          example: "Some unexpected error"
+          example: "Some unexpected error"
+
+    ErrorResponse:
+      type: object 
+      properties:
+        error:
+          $ref: "#/components/schemas/Error"
diff --git a/docs/design.md b/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