Merge pull request #3 from csatib02/docs/add-documentation

docs: add initial documentation
csatib02 · Sep 2, 2024 · 205627c · 205627c
2 parents 7385a6d + 5b695fd
commit 205627c
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 42 deletions.
diff --git a/README.md b/README.md
@@ -1,51 +1,19 @@
 # kube-pod-autocomplete
 
-Kube Pod Autocomplete is a Go-based backend service designed to enhance the user experience when navigating resource lists in Kubernetes clusters.
+*Kube Pod Autocomplete is a Go-based backend service designed to enhance the user experience when navigating resource lists in Kubernetes clusters.*
 
-## TODO
+## Getting started
+
+- Kube Pod Autocomplete is designed to be used in Kubernetes environment.
+- Take a look at the [documentation](./docs/docs.md).
 
-- Tool to check openapi againts own implementation
-- Create docs.
-- Add caching idea to docs.
+## TODO
 
-- Reconsider project layout.
 - Add e2e-tests.
 - Consider adding garden config to simplify testing.
 
 - Add search pods by label/ns/phase endpoint as a possible use-case.
 
-## Quick-start
-
-Create a Cluster:
-
-```shell
-make up
-```
-
-Deploy Kube Pod Autocomplete:
-
-```shell
-make deploy
-```
-
-Deploy some pods:
-
-```shell
-make deploy-testdata
-```
-
-Port-forward to Kube Pod Autocomplete:
-
-```shell
-kubectl port-forward -n kube-pod-autocomplete $(kubectl get pods -n kube-pod-autocomplete -o jsonpath='{.items[0].metadata.name}') 8080:8080 1>/dev/null &
-```
-
-Hit the endpoint:
-
-```shell
-curl http://localhost:8080/search/autocomplete/pods
-```
-
 ## Development
 
 Make sure Docker is installed.

diff --git a/docs/docs.md b/docs/docs.md
@@ -0,0 +1,51 @@
+# Kube Pod Autocomplete documentation
+
+Kube Pod Autocomplete is a service designed to enhance the user experience when navigating resource lists in Kubernetes clusters. It can retrieve specific data based on the requested resource type and supported filters.
+
+## Supported resources
+
+| **Resource**     | available Filters                     |
+|------------------|---------------------------------------|
+| pods ✅          | namespace, phase, labels, annotations |
+| services 🟡      | _Next up_                             |
+
+## API-Spec
+
+Checkout the [openapi](openapi.yaml) file, or use the [swagger spec](swagger.html).
+
+## Quick-start
+
+Create a Cluster:
+
+```shell
+make up
+```
+
+Deploy Kube Pod Autocomplete:
+
+```shell
+make deploy
+```
+
+Deploy some pods:
+
+```shell
+make deploy-testdata
+```
+
+Port-forward to Kube Pod Autocomplete:
+
+```shell
+kubectl port-forward -n kube-pod-autocomplete $(kubectl get pods -n kube-pod-autocomplete -o jsonpath='{.items[0].metadata.name}') 8080:8080 1>/dev/null &
+```
+
+Hit the endpoint:
+
+```shell
+curl -X GET http://localhost:8080/search/autocomplete/pods
+```
+
+## Future improvements
+
+- [ ] Add support for caching. (Based on tests with the current implementation with small amount of pods, the response speed is blazingly fast, but there can be problems in production environments.)
+- [ ] Generate API specification from OpenAPI spec. (The current implementation is a really simple POC, if the project is later expanded with additional endpoints code generation should be utilised.)
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
@@ -1,12 +1,14 @@
 openapi: 3.1.0
 info:
-  title: Autocomplete API
+  title: Kube Pod Autocomplete API
+  description: API for getting autocomplete suggestions for Kubernetes resources
   version: 1.0.0
 
 paths:
   /search/autocomplete/{resource}:
     get:
       summary: Get autocomplete suggestions
+      operationId: getAutocompleteSuggestions
       parameters:
         - name: resource
           in: path
@@ -41,6 +43,7 @@ paths:
   /health:
     get:
       summary: Health check
+      operationId: healthCheck
       responses:
         '200':
           description: Successful response
diff --git a/docs/swagger.html b/docs/swagger.html
@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>API Documentation</title>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.14/swagger-ui.css" />
+</head>
+<body>
+    <div id="swagger-ui"></div>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.14/swagger-ui-bundle.js"></script>
+    <script>
+        window.onload = () => {
+            SwaggerUIBundle({
+                url: "./openapi.yaml",
+                dom_id: '#swagger-ui',
+            });
+        };
+    </script>
+</body>
+</html>
diff --git a/pkg/http/http.go b/pkg/http/http.go
@@ -2,18 +2,18 @@ package http
 
 import "github.com/gin-gonic/gin"
 
-type HTTPError struct {
+type Error struct {
 	Code    int    `json:"code"`
 	Message string `json:"message"`
 }
 
-func (e *HTTPError) Error() string {
+func (e *Error) Error() string {
 	return e.Message
 }
 
 // HandleHTTPError is a utility function to handle HTTP errors in Gin handlers.
 func HandleHTTPError(c *gin.Context, code int, err error) {
-	httpErr := &HTTPError{
+	httpErr := &Error{
 		Code:    code,
 		Message: err.Error(),
 	}