feat(docs-openapi): update the docs and add openapi.yaml (#93)

README.md

@@ -1,3 +1,3 @@
 # FaaS Rust Implementation
 
-For development, check the [develop](docs/develop.md) guide.
+For development, check the [develop](https://github.com/faas-rs/faasd-in-rust/wiki/Setup-develop-environment) guide.

docs/develop.md

@@ -1,24 +0,0 @@
-# How to develop
-
-Thanks to the `nix`, we can easily develop the project in a reproducible environment. The following steps will guide you through the process.
-
-## nix environment
-> TODO
-
-## shell interactions
-
-There are several integrated nix commands that can help you develop the project.
-
-- `nix develop`
-    enter the default development shell
-- `nix build`
-    build the project, the result will be at `result/bin/faas-rs`
-- `nix flake check`
-    do the CI checks, including formatting, linting...
-
-Besides, you can also use the `cargo` command to interact with the project in the shell. Nix will automatically manage the toolchain and library dependencies for you.
-
-> [!NOTE]
-> The project uses `cargo-hakari`, to optimize the build time.
-
-If you don't know what it is, after new dependencies are added, you should run `cargo hakari generate` to update the dependencies.

docs/openapi.yaml

@@ -0,0 +1,191 @@
+openapi: 3.0.1
+info:
+  title: faasd-in-rs API Gateway
+  description: faasd-in-rs API documentation
+  license:
+    name: GPL-3.0
+  version: 0.1.0
+servers:
+- url: "http://localhost:8090"
+  description: Local server
+tags:
+  - name: internal
+    description: Internal use only
+  - name: system
+    description: System endpoints for managing functions and related objects
+  - name: function
+    description: Endpoints for invoking functions
+paths:
+  "/system/functions":
+    get:
+      operationId: GetFunctions
+      description: Get a list of deployed functions
+      summary: 'Get a list of deployed functions with: stats and image digest'
+      tags:
+        - system
+      responses:
+        '200':
+          description: List of deployed functions.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  "$ref": "#/components/schemas/FunctionStatus"
+        '400':
+          description: Bad Request
+        '500':
+          description: Internal Server Error
+    post:
+      operationId: DeployFunction
+      description: Deploy a new function.
+      summary: Deploy a new function.
+      tags:
+        - system
+      requestBody:
+        description: Function to deploy
+        content:
+          application/json:
+            schema:
+              "$ref": "#/components/schemas/FunctionDeployment"
+        required: true
+      responses:
+        '202':
+          description: Accepted
+        '400':
+          description: Bad Request
+        '500':
+          description: Internal Server Error
+    delete:
+      operationId: DeleteFunction
+      description: Remove a deployed function.
+      summary: Remove a deployed function.
+      tags:
+        - system
+      requestBody:
+        description: Function to delete
+        content:
+          application/json:
+            schema:
+              "$ref": "#/components/schemas/DeleteFunctionRequest"
+        required: true
+      responses:
+        '200':
+          description: OK
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
+  "/function/{function_name}":
+    post:
+      operationId: InvokeFunction
+      description: Invoke a function in the default namespace.
+      summary: |
+        Synchronously invoke a function defined in te default namespace.
+
+        Any additional path segments and query parameters will be passed to the function as is.
+      tags:
+        - function
+      parameters:
+      - name: function_name
+        in: path
+        description: Function name
+        required: true
+        schema:
+          type: string
+      requestBody:
+        description: "(Optional) data to pass to function"
+        content:
+          "*/*":
+            schema:
+              type: string
+              format: binary
+              example: '{"hello": "world"}'
+        required: false
+      responses:
+        '200':
+          description: Value returned from function
+        '404':
+          description: Not Found
+        '405':
+          description: Method Not Allowed
+        '500':
+          description: Internal server error
+
+components:
+  schemas:
+    FunctionDeployment:
+      required:
+      - function_name
+      - image
+      type: object
+      properties:
+        function_name:
+          type: string
+          description: Name of deployed function
+          example: nginx
+        image:
+          type: string
+          description: Docker image in accessible registry
+          example: docker.io/library/nginx:alpine
+        namespace:
+          type: string
+          description: Namespace to deploy function to. When omitted, the default namespace
+            is used, typically this is `faasd-in-rs-fn` but is configured by the provider.
+          example: faasd-in-rs-fn
+        envProcess:
+          type: string
+          description: |
+            Process for watchdog to fork, i.e. the command to start the function process.
+
+            This value configures the `fprocess` env variable.
+          example: main
+        envVars:
+          type: object
+          additionalProperties:
+            type: string
+          description: Overrides to environmental variables
+        labels:
+          type: object
+          nullable: true
+          additionalProperties:
+            type: string
+          description: A map of labels for making scheduling or routing decisions
+          example:
+            foo: bar
+    DeleteFunctionRequest:
+      required:
+      - function_name
+      type: object
+      properties:
+        function_name:
+          type: string
+          description: Name of deployed function
+          example: nginx
+    FunctionStatus:
+      type: object
+      required:
+        - function_name
+        - image
+      properties:
+        function_name:
+          type: string
+          description: The name of the function
+          example: nginx
+        image:
+          type: string
+          description: The fully qualified docker image name of the function
+          example: docker.io/library/nginx:alpine
+        namespace:
+          type: string
+          description: The namespace of the function
+          example: faasd-in-rs-fn
+        envProcess:
+          type: string
+          description: Process for watchdog to fork
+          example: main
+        envVars:
+          type: object
+          additionalProperties:
+            type: string
+          description: environment variables for the function runtime