Add an initial draft for the spec

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

api/openapi-spec/conventions-server..yaml

@@ -0,0 +1,88 @@
+openapi: 3.0.0
+info:
+  title: 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"
+      responses:
+        200:
+          description: Successfully applied added pod conventions
+          content:
+            "application/json":
+              schema:
+                $ref: '#/components/schemas/PodConventionContext'
+        400:
+          description: Error decoding request body into PodConventionContext type
+        500:
+          description: Internal server error
+          content:
+            "application/json":
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+components:
+  schemas:
+    PodConventionContext: 
+      type: object
+      properties:
+        spec:
+          $ref: "#/components/schemas/PodConventionContextSpec"
+        status:
+          $ref: "#/components/schemas/PodConventionContextStatus"
+    PodConventionContextSpec:
+      type: object
+      properties:
+        Template:
+          $ref: "#/components/schemas/PodTemplateSpec"
+        ImageConfig:
+          $ref: "#/components/schemas/ImageConfig"
+    PodConventionContextStatus:
+      type: object 
+      properties:
+        Template: 
+          $ref: "#/components/schemas/PodTemplateSpec"
+        appliedConventions:
+          description: a string array of conventions to be applied 
+          type: object 
+          example: ""
+    ImageConfig:
+      type: object 
+      properties: 
+        image: 
+          type: string 
+          description: a string reference to the image name and tag or associated digest
+        boms:
+          $ref: "#/components/schemas/BOM"
+        config: 
+          type: object 
+          description: "a ggcrv1 config file object"
+    BOM: 
+      type: object 
+      properties:
+        name: 
+          type: string 
+        raw: 
+          description: an array of bytes 
+    PodTemplateSpec:
+      type: object 
+      properties: 
+        spec: 
+          type: object 
+          description: corev1 PodSpec 
+    ErrorResponse:
+      type: object
+      properties:
+        error:
+          $ref: "#/components/schemas/Error"
+    Error:
+      type: object
+      properties:
+        message:
+          type: string
+          example: "Some unexpected error"

docs/design.md

@@ -244,14 +244,14 @@ In order for the conventions controller to apply a set of conventions, it requir
 
 The authored webhook is registered as follows:
   ```
-  http.HandleFunc(< url >, webhook.ConventionHandler(ctx, conventions_name))
+  http.HandleFunc(< path >, webhook.ConventionHandler(ctx, conventions_name))
   ```
-  The convention controller handler function expects a `ctx Context`  and a function describing conventions to be applied. See [springboot-convetions example](../samples/spring-convention-server/server.go)
+  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)
   ```
   http.HandleFunc("/", webhook.ConventionHandler(ctx, addSpringBootConventions))
   ```
-
-  The ```HandleFunc``` in ```cartographer-conventions``` is therefore responsible for invoking various reconcilers to apply the various conventions ordered by priority.
+  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) 
 
 ## Lifecycle