updated doc files

suxrobGM · Jul 27, 2024 · 03ba12f · 03ba12f
1 parent 63f7e01
commit 03ba12f
Show file tree

Hide file tree

Showing 7 changed files with 403 additions and 85 deletions.
diff --git a/README.md b/README.md
@@ -72,3 +72,8 @@ Once the projects are running, you can access them via the following URLs:
 - **FormBuilder.API**: The Web API project for managing form data and LOV (List of Values) data.
 - **FormBuilder.DesignerApp**: The Blazor WebAssembly project for designing and rendering forms.
 - **FormBuilder.Shared**: The shared project containing common models used across the `FormBuilder` and `FormBuilder.API` projects.
+
+## Documentation
+- **[API Reference](docs/api-reference.md)**: Learn how to use the Form Builder API to create, update, delete, and retrieve forms and LOV data.
+- **[Integration Guide](docs/integration-guide.md)**: Integrate the Blazor Form Builder with your existing Blazor application.
+- **[Form Renderer Component Reference](docs/form-renderer.md)**: Render forms in your Blazor application using the `FormRenderer` component.
diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -3,12 +3,256 @@
 The Form Builder REST API provides endpoints to manage forms and list of values (LOV).
 You can use the Form Builder API to create, update, delete, and retrieve forms and LOV data.
 
-## Form API
-- `GET /api/forms`: Get all forms in the form of paged response.
-    - Query Parameters:
-        - `page`: The non-zero-based page number. Default is 1.
-        - `pageSize`: The number of items per page. Default is 10.
-    - Response:
-        - `pageSize`: The number of items per page.
-        - `pagesCount`: The total number of available pages.
-        - `data`: An array of form data.
+All endpoints have general response structure, with `success`, `data`, and `error` fields.
+The `success` field indicates whether the request was successful.
+If the request was successful, the `data` field contains the response data. 
+Otherwise, the `error` field contains the error message and the `data` field is not present.
+
+```json
+{
+  "success": true,
+  "error": "Error message", // Only if success is false
+  "data": { // Only if success is true
+    "id": 1,
+    "formName": "Form 1",
+    "formDesign": "{JSON Data}"
+  }
+}
+```
+
+For pagination, the response contains `pageSize`, `pagesCount`, and `data` fields.
+```json
+{
+  "success": true,
+  "pageSize": 10, // Number of items per page
+  "pagesCount": 1, // Total number of pages
+  "data": [
+    {
+      "id": 1,
+      "formName": "Form 1",
+      "formDesign": "{JSON Data}"
+    }
+  ]
+}
+```
+
+#### GET `/api/forms`
+##### Summary:
+
+Gets a paged list of forms.
+
+##### Parameters
+
+| Name     | Located in | Description                                  | Required | Schema  |
+|----------|------------|----------------------------------------------|----------|---------|
+| OrderBy  | query      | The field to order by.                       | No       | string  |
+| Page     | query      | Non-zero-based page number. Default is 1.    | No       | integer |
+| PageSize | query      | The number of items per page. Default is 10. | No       | integer |
+
+##### Responses
+
+| Code | Description |
+|------|-------------|
+| 200  | Success     |
+
+Response body example,
+```json
+{
+  "success": true,
+  "pageSize": 10,
+  "pagesCount": 1,
+  "data": [
+    {
+      "id": 1,
+      "formName": "Form 1",
+      "formDesign": "{JSON Data}",
+    }
+  ]
+}
+```
+
+### POST `/api/forms`
+##### Summary:
+
+Creates a new form.
+
+##### Responses
+
+| Code | Description |
+|------|-------------|
+| 200  | Success     |
+| 400  | Bad Request |
+
+Success response body example,
+```json
+{
+  "success": true,
+  "data": {
+    "id": 1,
+    "formName": "Form 1",
+    "formDesign": "{JSON Data}"
+  }
+}
+```
+
+Error response body example,
+```json
+{
+  "success": false,
+  "error": "Error message"
+}
+```
+
+### GET `/api/forms/{id}`
+##### Summary:
+
+Gets a form by its id.
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| id | path | Form ID | Yes | string |
+
+##### Responses
+
+| Code | Description |
+|------|-------------|
+| 200  | Success     |
+| 400  | Bad Request |
+
+### PUT `/api/forms/{id}`
+##### Summary:
+
+Updates a form by its id.
+
+##### Parameters
+
+| Name | Located in | Description      | Required | Schema |
+|------|------------|------------------|----------|--------|
+| id   | path       | Existing form ID | Yes      | string |
+
+Example request body,
+```json
+{
+  "formName": "Form 1",
+  "formDesign": "{JSON Data}"
+}
+```
+
+##### Responses
+
+| Code | Description |
+|------|-------------|
+| 200  | Success     |
+| 400  | Bad Request |
+
+### DELETE `/api/forms/{id}`
+##### Summary:
+
+Deletes a form by its id.
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+|------|------------|-------------|----------|--------|
+| id   | path       | Form ID     | Yes      | string |
+
+##### Responses
+
+| Code | Description |
+|------|-------------|
+| 200  | Success     |
+| 400  | Bad Request |
+
+
+### GET `/api/lov`
+##### Summary:
+
+Gets a paged list of List IDs.
+
+##### Parameters
+
+| Name     | Located in | Description                                  | Required | Schema  |
+|----------|------------|----------------------------------------------|----------|---------|
+| OrderBy  | query      | The field to order by.                       | No       | string  |
+| Page     | query      | Non-zero-based page number. Default is 1.    | No       | integer |
+| PageSize | query      | The number of items per page. Default is 10. | No       | integer |
+
+##### Responses
+
+| Code | Description |
+|------|-------------|
+| 200  | Success     |
+
+### POST `/api/lov`
+##### Summary:
+
+Batch add list of values
+
+##### Responses
+
+| Code | Description |
+|------|-------------|
+| 200  | Success     |
+
+Request body example,
+```json
+{
+  "lovs": [
+    {
+      "listId": 1,
+      "listValue": "Value 1"
+    }
+  ]
+}
+```
+
+### GET `/api/lov/{listId}`
+##### Summary:
+
+Gets list of values filtered by ListId
+
+##### Parameters
+
+| Name   | Located in | Description | Required | Schema  |
+|--------|------------|-------------|----------|---------|
+| listId | path       |             | Yes      | integer |
+
+##### Responses
+
+| Code | Description |
+|------|-------------|
+| 200  | Success     |
+
+Success response body example,
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": 1,
+      "listId": 1,
+      "listValue": "Value 1"
+    }
+  ]
+}
+```
+
+### POST `/api/lov/batch-delete`
+##### Summary:
+
+Batch delete list of values
+
+##### Responses
+
+| Code | Description |
+|------|-------------|
+| 200  | Success     |
+
+Request body example,
+```json
+{
+  "listIds": [1, 2, 3]
+}
+```
diff --git a/docs/form-renderer.md b/docs/form-renderer.md
@@ -1,51 +1,66 @@
 # Form Renderer Component Reference
 
-The Form Renderer component is used to render forms in that designed by the `FormEditor` component.
+The Form Renderer component is used to render forms designed by the `FormEditor` component. 
 You can specify either the `FormId` or `FormJson` property to render a form.
 
 ## FormRenderer Properties
-- `FormId`: The ID of the form to render. It fetches form data from the API based on the ID.
-- `FormJson`: The JSON data of the form to render. You can pass the JSON data of the form directly to the component.
-- `IsLoadingForm`: A boolean value that indicates whether the form is loading and rendering.
+
+- **`FormId`**: The ID of the form to render. This fetches form data from the API based on the ID.
+- **`FormJson`**: The JSON data of the form to render. This allows you to pass the JSON data of the form directly to the component.
+- **`IsLoadingForm`**: A boolean value indicating whether the form is currently loading and rendering.
 
 ## FormRenderer Events
-- `IsLoadingFormChanged`: An event that is triggered when the `IsLoadingForm` property changes. You can use this event to perform additional actions when the form is loading.
-- `FormLoaded`: An event that is triggered when the form is loaded and rendered. You can use this event to perform additional actions when the form is loaded.
 
-## FormRenderer public methods
-- `LoadFormFromIdAsync(string formId)`: A method that loads the form data from the API based on the form ID.
-- `LoadFormFromJsonAsync(string formJson)`: A method that loads the form data from the JSON data.
-- `GetFormAsJsonAsync()`: A method that returns the JSON data of the rendered form.
+- **`IsLoadingFormChanged`**: An event triggered when the `IsLoadingForm` property changes. Use this event to perform additional actions when the form is loading.
+- **`FormLoaded`**: An event triggered when the form is fully loaded and rendered. Use this event to perform additional actions when the form is loaded.
+
+## FormRenderer Public Methods
+
+- **`LoadFormFromIdAsync(string formId)`**: Loads the form data from the API based on the form ID.
+- **`LoadFormFromJsonAsync(string formJson)`**: Loads the form data from the provided JSON data.
+- **`GetFormAsJsonAsync()`**: Returns the JSON data of the rendered form.
 
 ## Examples
-## Render a form using FormId or FormJson properties
+
+### Render a form using FormId or FormJson properties
+
+Render a form using the `FormId` property:
+
 ```html
 <FormRenderer FormId="1" />
 ```
+
+Render a form using the `FormJson` property:
+
 ```html
 <FormRenderer FormJson="@formJson" />
 ```
 
-## Render a form dynamically using methods
+### Render a form dynamically using methods
+
 ```html
 <FormRenderer @ref="formRendererRef" />
 
 <RadzenTextBox @bind-Value="_formId" />
 <RadzenButton Text="Load Form" Click="@LoadForm" />
 ```
+
 ```csharp
 @code {
     private FormRenderer? formRendererRef;
     private string? _formId;
-    
+
     private async Task LoadForm()
     {
         if (formRendererRef is null || string.IsNullOrEmpty(_formId))
         {
             return;
         }
-        
-        await formRenderer.LoadFormFromIdAsync(_formId);
+
+        await formRendererRef.LoadFormFromIdAsync(_formId);
     }
 }
 ```
+
+In these examples, the `FormRenderer` component can be used to dynamically load forms based on either a form ID or JSON data. 
+The component also provides events and methods to manage the loading state and retrieve the rendered form data as JSON.