Merge pull request #189 from sinamics/backend_api

Restfull API
sinamics · Oct 29, 2023 · 2a61cf5 · 2a61cf5
2 parents 2ebf44f + 090ce8f
commit 2a61cf5
Show file tree

Hide file tree

Showing 37 changed files with 6,582 additions and 1,258 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -6,5 +6,12 @@
     "[typescript]": {
         "editor.defaultFormatter": "rome.rome"
     },
-    "editor.tabSize": 2
+    "editor.defaultFormatter": "rome.rome",
+    "editor.tabSize": 2,
+    "[typescriptreact]": {
+        "editor.defaultFormatter": "rome.rome"
+    },
+    "yaml.schemas": {
+        "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json": "file:///workspaces/docs/ztnet/docs/Api/user/api.yml"
+    }
 }
diff --git a/docs/ztnet/docs/Rest Api/create-a-new-user.api.mdx b/docs/ztnet/docs/Rest Api/create-a-new-user.api.mdx
@@ -0,0 +1,48 @@
+---
+id: create-a-new-user
+title: "Create a new user"
+description: "If no users have been created yet, no API key is required. Otherwise, an API key must be included in the request header."
+sidebar_label: "Create a new user"
+hide_title: true
+hide_table_of_contents: true
+api: {"description":"If no users have been created yet, no API key is required. Otherwise, an API key must be included in the request header.\nKeep in mind that first user created will be the admin user.\n","security":[{"x-ztnet-auth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","password","name"],"properties":{"email":{"type":"string"},"password":{"type":"string"},"name":{"type":"string"},"expiresAt":{"type":"string | null","description":"The date and time at which the user's account will expire. If null, the account will never expire.\nMust be in ISO 8601 format (e.g. 2023-10-28T00:00:00Z).\n\nNot applicable if the user is an admin (first user). Admin accounts never expire.\n"}}},"example":{"email":"test@example.com","password":"password123","name":"Test User","expiresAt":"2023-10-28T00:00:00Z"}}}},"responses":{"200":{"description":"User successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"expiresAt":{"type":"string"}},"example":{"id":"12345","email":"test@example.com","name":"Test User","expiresAt":"2023-10-28T00:00:00Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}},"method":"post","path":"/api/v1/user","securitySchemes":{"x-ztnet-auth":{"type":"apiKey","required":true,"in":"header","name":"x-ztnet-auth","description":"API key can be generated from the ZTNet admin section."}},"jsonRequestBodyExample":{"email":"string","password":"string","name":"string"},"info":{"title":"ZTNet Web API","info_path":"restapi/ztnet-web-api","version":"1.0.0","description":"Public API for ZTNet. Available from ztnet version 0.4.0 onwards.\n\nThis API is rate-limited to 10 requests per minute\n"},"postman":{"name":"Create a new user","description":{"content":"If no users have been created yet, no API key is required. Otherwise, an API key must be included in the request header.\nKeep in mind that first user created will be the admin user.\n","type":"text/plain"},"url":{"path":["api","v1","user"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}},"auth":{"type":"apikey","apikey":[{"type":"any","value":"x-ztnet-auth","key":"key"},{"type":"any","value":"<API Key>","key":"value"},{"type":"any","value":"header","key":"in"}]}}}
+sidebar_class_name: "post api-method"
+info_path: Rest Api/ztnet-web-api
+custom_edit_url: null
+---
+
+import ApiTabs from "@theme/ApiTabs";
+import MimeTabs from "@theme/MimeTabs";
+import ParamsItem from "@theme/ParamsItem";
+import ResponseSamples from "@theme/ResponseSamples";
+import SchemaItem from "@theme/SchemaItem";
+import SchemaTabs from "@theme/SchemaTabs";
+import DiscriminatorTabs from "@theme/DiscriminatorTabs";
+import TabItem from "@theme/TabItem";
+
+## Create a new user
+
+
+
+If no users have been created yet, no API key is required. Otherwise, an API key must be included in the request header.
+Keep in mind that first user created will be the admin user.
+
+
+<MimeTabs><TabItem label={"application/json"} value={"application/json-schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Request Body</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"email"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"password"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"name"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"expiresAt"} required={false} schemaName={"string | null"} qualifierMessage={undefined} schema={{"type":"string | null","description":"The date and time at which the user's account will expire. If null, the account will never expire.\nMust be in ISO 8601 format (e.g. 2023-10-28T00:00:00Z).\n\nNot applicable if the user is an admin (first user). Admin accounts never expire.\n"}}></SchemaItem></ul></details></TabItem></MimeTabs><div><ApiTabs><TabItem label={"200"} value={"200"}><div>
+
+User successfully created
+
+</div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"id"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"email"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"name"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"expiresAt"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"id\": \"12345\",\n  \"email\": \"test@example.com\",\n  \"name\": \"Test User\",\n  \"expiresAt\": \"2023-10-28T00:00:00Z\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem><TabItem label={"401"} value={"401"}><div>
+
+Unauthorized
+
+</div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"error"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"error\": \"string\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem><TabItem label={"429"} value={"429"}><div>
+
+Rate limit exceeded
+
+</div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"error"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"error\": \"string\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem><TabItem label={"500"} value={"500"}><div>
+
+Internal server error
+
+</div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"string\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>
+
diff --git a/docs/ztnet/docs/Rest Api/source/user.yml b/docs/ztnet/docs/Rest Api/source/user.yml
@@ -0,0 +1,112 @@
+openapi: 3.1.0
+info:
+  title: ZTNet Web API
+  info_path: restapi/ztnet-web-api
+  version: 1.0.0
+  description: |
+    Public API for ZTNet. Available from ztnet version 0.4.0 onwards.
+    
+    This API is rate-limited to 10 requests per minute
+paths:
+  /api/v1/user:
+    post:
+      summary: Create a new user
+      description: |
+        If no users have been created yet, no API key is required. Otherwise, an API key must be included in the request header.
+        Keep in mind that first user created will be the admin user.
+      security:
+        - x-ztnet-auth: []
+      requestBody:
+        # required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+                - password
+                - name
+              properties:
+                email:
+                  type: string
+                password:
+                  type: string
+                name:
+                  type: string
+                expiresAt:
+                  type: string | null
+                  description: |
+                    The date and time at which the user's account will expire. If null, the account will never expire.
+                    Must be in ISO 8601 format (e.g. 2023-10-28T00:00:00Z).
+
+                    Not applicable if the user is an admin (first user). Admin accounts never expire.
+            example:
+              email: "test@example.com"
+              password: "password123"
+              name: "Test User"
+              expiresAt: "2023-10-28T00:00:00Z"
+      # parameters:
+      #   - name: x-ztnet-auth
+      #     in: header
+      #     required: true
+      #     schema:
+      #       type: string
+      #     description: API key required if any users have been created.
+
+      responses:
+        200:
+          description: User successfully created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  email:
+                    type: string
+                  name:
+                    type: string
+                  expiresAt:
+                    type: string
+                example:
+                  id: "12345"
+                  email: "test@example.com"
+                  name: "Test User"
+                  expiresAt: "2023-10-28T00:00:00Z"
+
+        401:
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+        429:
+          description: Rate limit exceeded
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+        500:
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+components:
+  securitySchemes:
+    x-ztnet-auth:
+      type: apiKey
+      required: true
+      in: header
+      name: x-ztnet-auth
+      description: API key can be generated from the ZTNet admin section.
diff --git a/docs/ztnet/docs/Rest Api/ztnet-web-api.info.mdx b/docs/ztnet/docs/Rest Api/ztnet-web-api.info.mdx
@@ -0,0 +1,32 @@
+---
+id: ztnet-web-api
+title: "ZTNet Web API"
+description: "Public API for ZTNet. Available from ztnet version 0.4.0 onwards."
+sidebar_label: Introduction
+sidebar_position: 0
+hide_title: true
+custom_edit_url: null
+---
+
+import ApiLogo from "@theme/ApiLogo";
+import SchemaTabs from "@theme/SchemaTabs";
+import TabItem from "@theme/TabItem";
+import Export from "@theme/ApiDemoPanel/Export";
+
+<span className={"theme-doc-version-badge badge badge--secondary"}>Version: 1.0.0</span>
+
+# ZTNet Web API
+
+
+
+Public API for ZTNet. Available from ztnet version 0.4.0 onwards.
+
+This API is rate-limited to 10 requests per minute
+
+
+<div style={{"marginBottom":"2rem"}}><h2 id={"authentication"} style={{"marginBottom":"1rem"}}>Authentication</h2><SchemaTabs className={"openapi-tabs__security-schemes"}><TabItem label={"API Key: x-ztnet-auth"} value={"x-ztnet-auth"}>
+
+API key can be generated from the ZTNet admin section.
+
+<div><table><tbody><tr><th>Security Scheme Type:</th><td>apiKey</td></tr><tr><th>Header parameter name:</th><td>x-ztnet-auth</td></tr></tbody></table></div></TabItem></SchemaTabs></div>
+
diff --git a/docs/ztnet/docusaurus.config.js b/docs/ztnet/docusaurus.config.js
@@ -32,12 +32,30 @@ const config = {
     defaultLocale: 'en',
     locales: ['en'],
   },
+  plugins: [
+    [
+      'docusaurus-plugin-openapi-docs',
+      {
+        id: "api", // plugin id
+        docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs
+        config: {
+          user: { // the <id> referenced when running CLI commands
+            specPath: "docs/Rest Api/source/user.yml", // path to OpenAPI spec, URLs supported
+            outputDir: "docs/Rest Api" // output directory for generated files
+          },
+        }
+      },
+    ]
+  ],
+  themes: ["docusaurus-theme-openapi-docs"], // export theme components
   presets: [
     [
       'classic',
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
+          docLayoutComponent: "@theme/DocPage",
+          docItemComponent: "@theme/ApiItem",
           routeBasePath: '/', // Set this value to '/'.
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.