Feat/open api spec (#168)

* feat: add initial api spec

* feat: link appflowy root readme to openapi

documentation/appflowy-cloud/.openapi-generator-ignore

@@ -0,0 +1,23 @@
+# OpenAPI Generator Ignore
+# Generated by openapi-generator https://github.com/openapitools/openapi-generator
+
+# Use this file to prevent files from being overwritten by the generator.
+# The patterns follow closely to .gitignore or .dockerignore.
+
+# As an example, the C# client generator defines ApiClient.cs.
+# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line:
+#ApiClient.cs
+
+# You can match any string of characters against a directory, file or extension with a single asterisk (*):
+#foo/*/qux
+# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux
+
+# You can recursively match patterns against a directory, file or extension with a double asterisk (**):
+#foo/**/qux
+# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux
+
+# You can also negate patterns with an exclamation (!).
+# For example, you can ignore all files in a docs folder with the file extension .md:
+#docs/*.md
+# Then explicitly reverse the ignore rule for a single file:
+#!docs/README.md

documentation/appflowy-cloud/.openapi-generator/FILES

@@ -0,0 +1,7 @@
+.openapi-generator-ignore
+Apis/WorkspacesApi.md
+Models/GenericApiResponse.md
+Models/Role.md
+Models/Workspace.md
+Models/getWorkspaces_200_response.md
+README.md

documentation/appflowy-cloud/.openapi-generator/VERSION

@@ -0,0 +1 @@
+7.10.0

documentation/appflowy-cloud/README.md

@@ -1,2 +1,4 @@
 # ☁ AppFlowy Cloud
 
+## OpenAPI Specification
+[Documentation](./openapi/README.md)

documentation/appflowy-cloud/openapi/.gitignore

@@ -0,0 +1 @@
+node_modules/

documentation/appflowy-cloud/openapi/.openapi-generator-ignore

@@ -0,0 +1,23 @@
+# OpenAPI Generator Ignore
+# Generated by openapi-generator https://github.com/openapitools/openapi-generator
+
+# Use this file to prevent files from being overwritten by the generator.
+# The patterns follow closely to .gitignore or .dockerignore.
+
+# As an example, the C# client generator defines ApiClient.cs.
+# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line:
+#ApiClient.cs
+
+# You can match any string of characters against a directory, file or extension with a single asterisk (*):
+#foo/*/qux
+# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux
+
+# You can recursively match patterns against a directory, file or extension with a double asterisk (**):
+#foo/**/qux
+# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux
+
+# You can also negate patterns with an exclamation (!).
+# For example, you can ignore all files in a docs folder with the file extension .md:
+#docs/*.md
+# Then explicitly reverse the ignore rule for a single file:
+#!docs/README.md

documentation/appflowy-cloud/openapi/.openapi-generator/FILES

@@ -0,0 +1,6 @@
+Apis/WorkspacesApi.md
+Models/getWorkspaces_200_response.md
+Models/response.md
+Models/role.md
+Models/workspace.md
+README.md

documentation/appflowy-cloud/openapi/.openapi-generator/VERSION

@@ -0,0 +1 @@
+7.10.0

documentation/appflowy-cloud/openapi/Apis/WorkspacesApi.md

@@ -0,0 +1,37 @@
+# WorkspacesApi
+
+All URIs are relative to *https://beta.appflowy.cloud/api*
+
+| Method | HTTP request | Description |
+|------------- | ------------- | -------------|
+| [**getWorkspaces**](WorkspacesApi.md#getWorkspaces) | **GET** /workspace | Retrieves a list of all workspaces |
+
+
+<a name="getWorkspaces"></a>
+# **getWorkspaces**
+> getWorkspaces_200_response getWorkspaces(include\_member\_count, include\_role)
+
+Retrieves a list of all workspaces
+
+    This endpoint fetches a list of workspaces along with detailed information about each workspace, such as the workspace ID, owner information, and workspace properties like name, type, and icon. 
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **include\_member\_count** | **Boolean**| Include the count of members in each workspace when set to true. | [optional] [default to null] |
+| **include\_role** | **Boolean**| Include the role of the user making the request in the workspace details when set to true. | [optional] [default to null] |
+
+### Return type
+
+[**getWorkspaces_200_response**](../Models/getWorkspaces_200_response.md)
+
+### Authorization
+
+[BearerAuth](../README.md#BearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+

documentation/appflowy-cloud/openapi/HOWTO.md

@@ -0,0 +1,16 @@
+# Generator for [OpenAPI specification](https://spec.openapis.org/)
+
+## Installation
+Follow the instructions at [OpenAPI Generator](https://openapi-generator.tech/docs/installation) to install the generator.
+
+## Validation
+To validate the OpenAPI specification, use the following command:
+
+```bash
+openapi-generator-cli validate -i openapi.yaml
+```
+
+## Generation
+```bash
+openapi-generator-cli generate -i openapi.yaml -g markdown
+```

documentation/appflowy-cloud/openapi/Models/GenericApiResponse.md

@@ -0,0 +1,10 @@
+# GenericApiResponse
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **code** | **Integer** | Numeric code indicating the success or failure of the API call. | [optional] [default to null] |
+| **message** | **String** | A message providing additional information about the API call result. | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

documentation/appflowy-cloud/openapi/Models/Role.md

@@ -0,0 +1,8 @@
+# Role
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

documentation/appflowy-cloud/openapi/Models/Workspace.md

@@ -0,0 +1,19 @@
+# Workspace
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **workspace\_id** | **UUID** | The unique identifier for the workspace. | [optional] [default to null] |
+| **database\_storage\_id** | **UUID** | Identifier for the database storage associated with this workspace. | [optional] [default to null] |
+| **owner\_uid** | **Long** | The unique identifier of the workspace owner. | [optional] [default to null] |
+| **owner\_name** | **String** | The name of the workspace owner. | [optional] [default to null] |
+| **owner\_email** | **String** | The email address of the workspace owner. | [optional] [default to null] |
+| **workspace\_type** | **Integer** | The type of workspace, represented as an integer. | [optional] [default to null] |
+| **workspace\_name** | **String** | The human-readable name of the workspace. | [optional] [default to null] |
+| **created\_at** | **Date** | The ISO 8601 date and time when the workspace was created. | [optional] [default to null] |
+| **icon** | **String** | An optional icon represented as a Unicode character or an image URL. | [optional] [default to null] |
+| **member\_count** | **Long** | The number of members in the workspace, if available. | [optional] [default to null] |
+| **role** | [**Role**](Role.md) |  | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

documentation/appflowy-cloud/openapi/Models/getWorkspaces_200_response.md

@@ -0,0 +1,11 @@
+# getWorkspaces_200_response
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **code** | **Integer** | Numeric code indicating the success or failure of the API call. | [optional] [default to null] |
+| **message** | **String** | A message providing additional information about the API call result. | [optional] [default to null] |
+| **data** | [**List**](workspace.md) |  | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

documentation/appflowy-cloud/openapi/Models/response.md

@@ -0,0 +1,10 @@
+# response
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **code** | **Integer** | Numeric code indicating the success or failure of the API call. | [optional] [default to null] |
+| **message** | **String** | A message providing additional information about the API call result. | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

documentation/appflowy-cloud/openapi/Models/role.md

@@ -0,0 +1,8 @@
+# role
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

documentation/appflowy-cloud/openapi/Models/workspace.md

@@ -0,0 +1,19 @@
+# workspace
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **workspace\_id** | **UUID** | The unique identifier for the workspace. | [optional] [default to null] |
+| **database\_storage\_id** | **UUID** | Identifier for the database storage associated with this workspace. | [optional] [default to null] |
+| **owner\_uid** | **Long** | The unique identifier of the workspace owner. | [optional] [default to null] |
+| **owner\_name** | **String** | The name of the workspace owner. | [optional] [default to null] |
+| **owner\_email** | **String** | The email address of the workspace owner. | [optional] [default to null] |
+| **workspace\_type** | **Integer** | The type of workspace, represented as an integer. | [optional] [default to null] |
+| **workspace\_name** | **String** | The human-readable name of the workspace. | [optional] [default to null] |
+| **created\_at** | **Date** | The ISO 8601 date and time when the workspace was created. | [optional] [default to null] |
+| **icon** | **String** | An optional icon represented as a Unicode character or an image URL. | [optional] [default to null] |
+| **member\_count** | **Long** | The number of members in the workspace, if available. | [optional] [default to null] |
+| **role** | [**role**](role.md) |  | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

documentation/appflowy-cloud/openapi/README.md

@@ -0,0 +1,29 @@
+# Documentation for AppFlowy REST API
+
+<a name="documentation-for-api-endpoints"></a>
+## Documentation for API Endpoints
+
+All URIs are relative to *https://beta.appflowy.cloud/api*
+
+| Class | Method | HTTP request | Description |
+|------------ | ------------- | ------------- | -------------|
+| *WorkspacesApi* | [**getWorkspaces**](Apis/WorkspacesApi.md#getworkspaces) | **GET** /workspace | Retrieves a list of all workspaces |
+
+
+<a name="documentation-for-models"></a>
+## Documentation for Models
+
+ - [getWorkspaces_200_response](./Models/getWorkspaces_200_response.md)
+ - [response](./Models/response.md)
+ - [role](./Models/role.md)
+ - [workspace](./Models/workspace.md)
+
+
+<a name="documentation-for-authorization"></a>
+## Documentation for Authorization
+
+<a name="BearerAuth"></a>
+### BearerAuth
+
+- **Type**: HTTP Bearer Token authentication (JWT)
+

documentation/appflowy-cloud/openapi/components/response.yaml

@@ -0,0 +1,9 @@
+type: object
+properties:
+  code:
+    type: integer
+    format: int32
+    description: Numeric code indicating the success or failure of the API call.
+  message:
+    type: string
+    description: A message providing additional information about the API call result.

documentation/appflowy-cloud/openapi/components/role.yaml

@@ -0,0 +1,10 @@
+type: integer
+description: >
+  Role of the user within the workspace. Roles include:
+  1: Owner - Has full control over the workspace.
+  2: Member - Has regular access to the workspace.
+  3: Guest - Has limited access to the workspace.
+enum:
+  - 1
+  - 2
+  - 3

documentation/appflowy-cloud/openapi/components/workspace.yaml

@@ -0,0 +1,43 @@
+type: object
+properties:
+  workspace_id:
+    type: string
+    format: uuid
+    description: The unique identifier for the workspace.
+  database_storage_id:
+    type: string
+    format: uuid
+    description: Identifier for the database storage associated with this workspace.
+  owner_uid:
+    type: integer
+    format: int64
+    description: The unique identifier of the workspace owner.
+  owner_name:
+    type: string
+    description: The name of the workspace owner.
+  owner_email:
+    type: string
+    description: The email address of the workspace owner.
+  workspace_type:
+    type: integer
+    description: The type of workspace, represented as an integer.
+  workspace_name:
+    type: string
+    description: The human-readable name of the workspace.
+  created_at:
+    type: string
+    format: date-time
+    description: The ISO 8601 date and time when the workspace was created.
+  icon:
+    type: string
+    description: An optional icon represented as a Unicode character or an image URL.
+    nullable: true
+  member_count:
+    type: integer
+    format: int64
+    description: The number of members in the workspace, if available.
+    nullable: true
+  role:
+    $ref: './role.yaml'
+    description: The role of the user requesting the workspace details.
+    nullable: true

documentation/appflowy-cloud/openapi/openapi.yaml

@@ -0,0 +1,15 @@
+openapi: "3.0.2"
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+info:
+  title: AppFlowy REST API
+  version: 1.0.0
+servers:
+  - url: https://beta.appflowy.cloud/api
+paths:
+  /workspace:
+    $ref: './paths/workspace.yaml'

documentation/appflowy-cloud/openapi/openapitools.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
+  "spaces": 2,
+  "generator-cli": {
+    "version": "7.10.0"
+  }
+}

documentation/appflowy-cloud/openapi/paths/workspace.yaml

@@ -0,0 +1,37 @@
+get:
+  summary: Retrieves a list of all workspaces
+  security:
+    - BearerAuth: []
+  description: >
+    This endpoint fetches a list of workspaces along with detailed information about each workspace,
+    such as the workspace ID, owner information, and workspace properties like name, type, and icon.
+  operationId: getWorkspaces
+  tags:
+    - Workspaces
+  parameters:
+    - name: include_member_count
+      in: query
+      description: Include the count of members in each workspace when set to true.
+      required: false
+      schema:
+        type: boolean
+    - name: include_role
+      in: query
+      description: Include the role of the user making the request in the workspace details when set to true.
+      required: false
+      schema:
+        type: boolean
+  responses:
+    '200':
+      description: Successfully retrieved the list of workspaces
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: '../components/response.yaml'
+              - type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '../components/workspace.yaml'