From 1b75ae7e4195babc70a4de6d69cdf4b2f1c17c75 Mon Sep 17 00:00:00 2001 From: Zack Fu Zi Xiang Date: Thu, 19 Dec 2024 22:58:56 +0800 Subject: [PATCH 1/2] feat: add initial api spec --- .../appflowy-cloud/.openapi-generator-ignore | 23 ++++++++++ .../appflowy-cloud/.openapi-generator/FILES | 7 +++ .../appflowy-cloud/.openapi-generator/VERSION | 1 + .../appflowy-cloud/openapi/.gitignore | 1 + .../openapi/.openapi-generator-ignore | 23 ++++++++++ .../openapi/.openapi-generator/FILES | 6 +++ .../openapi/.openapi-generator/VERSION | 1 + .../openapi/Apis/WorkspacesApi.md | 37 ++++++++++++++++ documentation/appflowy-cloud/openapi/HOWTO.md | 16 +++++++ .../openapi/Models/GenericApiResponse.md | 10 +++++ .../appflowy-cloud/openapi/Models/Role.md | 8 ++++ .../openapi/Models/Workspace.md | 19 ++++++++ .../Models/getWorkspaces_200_response.md | 11 +++++ .../appflowy-cloud/openapi/Models/response.md | 10 +++++ .../appflowy-cloud/openapi/Models/role.md | 8 ++++ .../openapi/Models/workspace.md | 19 ++++++++ .../appflowy-cloud/openapi/README.md | 29 +++++++++++++ .../openapi/components/response.yaml | 9 ++++ .../openapi/components/role.yaml | 10 +++++ .../openapi/components/workspace.yaml | 43 +++++++++++++++++++ .../appflowy-cloud/openapi/openapi.yaml | 15 +++++++ .../appflowy-cloud/openapi/openapitools.json | 7 +++ .../openapi/paths/workspace.yaml | 37 ++++++++++++++++ 23 files changed, 350 insertions(+) create mode 100644 documentation/appflowy-cloud/.openapi-generator-ignore create mode 100644 documentation/appflowy-cloud/.openapi-generator/FILES create mode 100644 documentation/appflowy-cloud/.openapi-generator/VERSION create mode 100644 documentation/appflowy-cloud/openapi/.gitignore create mode 100644 documentation/appflowy-cloud/openapi/.openapi-generator-ignore create mode 100644 documentation/appflowy-cloud/openapi/.openapi-generator/FILES create mode 100644 documentation/appflowy-cloud/openapi/.openapi-generator/VERSION create mode 100644 documentation/appflowy-cloud/openapi/Apis/WorkspacesApi.md create mode 100644 documentation/appflowy-cloud/openapi/HOWTO.md create mode 100644 documentation/appflowy-cloud/openapi/Models/GenericApiResponse.md create mode 100644 documentation/appflowy-cloud/openapi/Models/Role.md create mode 100644 documentation/appflowy-cloud/openapi/Models/Workspace.md create mode 100644 documentation/appflowy-cloud/openapi/Models/getWorkspaces_200_response.md create mode 100644 documentation/appflowy-cloud/openapi/Models/response.md create mode 100644 documentation/appflowy-cloud/openapi/Models/role.md create mode 100644 documentation/appflowy-cloud/openapi/Models/workspace.md create mode 100644 documentation/appflowy-cloud/openapi/README.md create mode 100644 documentation/appflowy-cloud/openapi/components/response.yaml create mode 100644 documentation/appflowy-cloud/openapi/components/role.yaml create mode 100644 documentation/appflowy-cloud/openapi/components/workspace.yaml create mode 100644 documentation/appflowy-cloud/openapi/openapi.yaml create mode 100644 documentation/appflowy-cloud/openapi/openapitools.json create mode 100644 documentation/appflowy-cloud/openapi/paths/workspace.yaml diff --git a/documentation/appflowy-cloud/.openapi-generator-ignore b/documentation/appflowy-cloud/.openapi-generator-ignore new file mode 100644 index 0000000..7484ee5 --- /dev/null +++ b/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 diff --git a/documentation/appflowy-cloud/.openapi-generator/FILES b/documentation/appflowy-cloud/.openapi-generator/FILES new file mode 100644 index 0000000..f505fe2 --- /dev/null +++ b/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 diff --git a/documentation/appflowy-cloud/.openapi-generator/VERSION b/documentation/appflowy-cloud/.openapi-generator/VERSION new file mode 100644 index 0000000..758bb9c --- /dev/null +++ b/documentation/appflowy-cloud/.openapi-generator/VERSION @@ -0,0 +1 @@ +7.10.0 diff --git a/documentation/appflowy-cloud/openapi/.gitignore b/documentation/appflowy-cloud/openapi/.gitignore new file mode 100644 index 0000000..c2658d7 --- /dev/null +++ b/documentation/appflowy-cloud/openapi/.gitignore @@ -0,0 +1 @@ +node_modules/ diff --git a/documentation/appflowy-cloud/openapi/.openapi-generator-ignore b/documentation/appflowy-cloud/openapi/.openapi-generator-ignore new file mode 100644 index 0000000..7484ee5 --- /dev/null +++ b/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 diff --git a/documentation/appflowy-cloud/openapi/.openapi-generator/FILES b/documentation/appflowy-cloud/openapi/.openapi-generator/FILES new file mode 100644 index 0000000..74a60b0 --- /dev/null +++ b/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 diff --git a/documentation/appflowy-cloud/openapi/.openapi-generator/VERSION b/documentation/appflowy-cloud/openapi/.openapi-generator/VERSION new file mode 100644 index 0000000..758bb9c --- /dev/null +++ b/documentation/appflowy-cloud/openapi/.openapi-generator/VERSION @@ -0,0 +1 @@ +7.10.0 diff --git a/documentation/appflowy-cloud/openapi/Apis/WorkspacesApi.md b/documentation/appflowy-cloud/openapi/Apis/WorkspacesApi.md new file mode 100644 index 0000000..f79bc0f --- /dev/null +++ b/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 | + + + +# **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 + diff --git a/documentation/appflowy-cloud/openapi/HOWTO.md b/documentation/appflowy-cloud/openapi/HOWTO.md new file mode 100644 index 0000000..2c224ad --- /dev/null +++ b/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 +``` diff --git a/documentation/appflowy-cloud/openapi/Models/GenericApiResponse.md b/documentation/appflowy-cloud/openapi/Models/GenericApiResponse.md new file mode 100644 index 0000000..d4c8939 --- /dev/null +++ b/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) + diff --git a/documentation/appflowy-cloud/openapi/Models/Role.md b/documentation/appflowy-cloud/openapi/Models/Role.md new file mode 100644 index 0000000..12619ae --- /dev/null +++ b/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) + diff --git a/documentation/appflowy-cloud/openapi/Models/Workspace.md b/documentation/appflowy-cloud/openapi/Models/Workspace.md new file mode 100644 index 0000000..4477e5c --- /dev/null +++ b/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) + diff --git a/documentation/appflowy-cloud/openapi/Models/getWorkspaces_200_response.md b/documentation/appflowy-cloud/openapi/Models/getWorkspaces_200_response.md new file mode 100644 index 0000000..0f61afa --- /dev/null +++ b/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) + diff --git a/documentation/appflowy-cloud/openapi/Models/response.md b/documentation/appflowy-cloud/openapi/Models/response.md new file mode 100644 index 0000000..f8db987 --- /dev/null +++ b/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) + diff --git a/documentation/appflowy-cloud/openapi/Models/role.md b/documentation/appflowy-cloud/openapi/Models/role.md new file mode 100644 index 0000000..251c1af --- /dev/null +++ b/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) + diff --git a/documentation/appflowy-cloud/openapi/Models/workspace.md b/documentation/appflowy-cloud/openapi/Models/workspace.md new file mode 100644 index 0000000..73cc557 --- /dev/null +++ b/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) + diff --git a/documentation/appflowy-cloud/openapi/README.md b/documentation/appflowy-cloud/openapi/README.md new file mode 100644 index 0000000..c497bf6 --- /dev/null +++ b/documentation/appflowy-cloud/openapi/README.md @@ -0,0 +1,29 @@ +# Documentation for AppFlowy REST API + + +## 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 | + + + +## Documentation for Models + + - [getWorkspaces_200_response](./Models/getWorkspaces_200_response.md) + - [response](./Models/response.md) + - [role](./Models/role.md) + - [workspace](./Models/workspace.md) + + + +## Documentation for Authorization + + +### BearerAuth + +- **Type**: HTTP Bearer Token authentication (JWT) + diff --git a/documentation/appflowy-cloud/openapi/components/response.yaml b/documentation/appflowy-cloud/openapi/components/response.yaml new file mode 100644 index 0000000..1e9303f --- /dev/null +++ b/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. diff --git a/documentation/appflowy-cloud/openapi/components/role.yaml b/documentation/appflowy-cloud/openapi/components/role.yaml new file mode 100644 index 0000000..d3a6843 --- /dev/null +++ b/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 diff --git a/documentation/appflowy-cloud/openapi/components/workspace.yaml b/documentation/appflowy-cloud/openapi/components/workspace.yaml new file mode 100644 index 0000000..3739824 --- /dev/null +++ b/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 diff --git a/documentation/appflowy-cloud/openapi/openapi.yaml b/documentation/appflowy-cloud/openapi/openapi.yaml new file mode 100644 index 0000000..dffb207 --- /dev/null +++ b/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' diff --git a/documentation/appflowy-cloud/openapi/openapitools.json b/documentation/appflowy-cloud/openapi/openapitools.json new file mode 100644 index 0000000..f8d07ce --- /dev/null +++ b/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" + } +} diff --git a/documentation/appflowy-cloud/openapi/paths/workspace.yaml b/documentation/appflowy-cloud/openapi/paths/workspace.yaml new file mode 100644 index 0000000..1f8623a --- /dev/null +++ b/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' From afec0dc5ce6dd97f792eae067529f95b2e85c52c Mon Sep 17 00:00:00 2001 From: Zack Fu Zi Xiang Date: Thu, 19 Dec 2024 23:49:08 +0800 Subject: [PATCH 2/2] feat: link appflowy root readme to openapi --- documentation/appflowy-cloud/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/documentation/appflowy-cloud/README.md b/documentation/appflowy-cloud/README.md index 55c7153..4a71628 100644 --- a/documentation/appflowy-cloud/README.md +++ b/documentation/appflowy-cloud/README.md @@ -1,2 +1,4 @@ # ☁ AppFlowy Cloud +## OpenAPI Specification +[Documentation](./openapi/README.md)