Api documentation update

api/README.md

@@ -4,20 +4,31 @@ An extension to the Kubeflow Pipeline API for Components and Models
 
 ---
 
-# Quickstart    
+# MLX API Codegen Workflow
 
-## Deploy to Kubernetes
+![This is an image](https://github.com/psspavan96/mlx/blob/API_Documentation_update/api/API_Codegen_Workflow.png)
 
-    kubectl apply -f ./server/mlx-api.yml
+- The generation of Python code starts from Swagger Spec. The generated code has 2 outputs: the /api/client and the /api/server packages.
+- No static HTML documentation gets generated from Swagger Spec. The Swagger UI will be generated on the fly when the Python server is started. There are some docs under the client package, but those are in Markdown format which works well when browsing through the Github repo.
+- The /api/client/docs contains some examples from which we create the Python scripts in the /api/examples package.
+- Once the server code is generated we need to copy any new API method stubs (if any new) from the /api/server/swagger_server/controllers folder to the /api/server/swagger_server/controllers_impl folder and actually write the business logic. If existing API method signatures got updated, we need to update the existing controller_impl methods respectively.
+
+
+
+# Deploy to Kubernetes    
+
+1) Run kubectl command to apply the manifest
+
+    `kubectl apply -f ./server/mlx-api.yml`
 
-## Find API Server Host and Port
+2) Find API Server Host and Port
 
-    export API_HOST=$(kubectl get nodes -o jsonpath='{.items[].status.addresses[?(@.type=="ExternalIP")].address}')
-    export API_PORT=$(kubectl get service mlx-api -n kubeflow -o jsonpath='{.spec.ports[0].nodePort}')
+    `export API_HOST=$(kubectl get nodes -o jsonpath='{.items[].status.addresses[?(@.type=="ExternalIP")].address}')`
+    `export API_PORT=$(kubectl get service mlx-api -n kubeflow -o jsonpath='{.spec.ports[0].nodePort}')`
 
-## Open the Swagger UI in a Web Browser
+3) Open the Swagger UI in a Web Browser
 
-    open "http://${API_HOST}:${API_PORT}/apis/v1alpha1/ui/"
+    `open "http://${API_HOST}:${API_PORT}/apis/v1alpha1/ui/" `
 
 ---
 

api/server/README.md

@@ -8,6 +8,20 @@ Flask server.
 
 This example uses the [Connexion](https://github.com/zalando/connexion) library on top of Flask.
 
+## MLX API Server Components Functions
+
+| Python package/script  | Purpose |
+| ------------- | ------------- |
+| `code_templates`  | Code templates are used to generate sample Kubeflow pipeline DSL scripts for each asset type  |
+| `controllers`  | Controllers are the code stubs (“interfaces”) for the API endpoints generated by Swagger  |
+| `controllers_impl` | Controller implementation of the generated API code stubs (“interfaces”), originally copied from respective controller and then filled in with the actual business logic. API calls get forwards from the controllers to the controller_impl by injection of some code magic in util.py (see codegen.sh) |
+| `data_access` | Contains 2 clients - MySQL (relational database) and Minio (object storage) for data access |
+| `gateways` | Connects the API server to various services on the Kubernetes cluster like KFServing, Kubeflow Pipelines, and the Kubernetes API |
+| `models` | Swagger generated API classes used to transfer data between API client and API server |
+| `encoder.py` | Implementation of JSON encoder (generated by Swagger) |
+| `util.py` | Collection of helper functions, most notably to “glue” the API `controllers` code stubs to the `controllers_impl` API implementations |
+
+
 ## Requirements
 Python 3.6.1+