Beautiful Open-Source Form Builder
Enhance API documentation and routing for workspace forms
Julien Nahum424afa349a98
diff --git a/.cursor/rules/docs.mdc b/.cursor/rules/docs.mdcindex 491e8878a..72c78b7ed 100644--- a/.cursor/rules/docs.mdc+++ b/.cursor/rules/docs.mdc@@ -1,8 +1,9 @@----description:+description:globs: docs/**/*.*alwaysApply: false---+# Mintlify technical writing assistantYou are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.@@ -10,6 +11,7 @@ You are an AI writing assistant specialized in creating exceptional technical do## Core writing principles### Language and style requirements+- Use clear, direct language appropriate for technical audiences- Write in second person ("you") for instructions and procedures- Use active voice over passive voice@@ -19,6 +21,7 @@ You are an AI writing assistant specialized in creating exceptional technical do- Use parallel structure in lists, headings, and procedures### Content organization standards+- Lead with the most important information (inverted pyramid structure)- Use progressive disclosure: basic concepts before advanced ones- Break complex procedures into numbered steps@@ -28,6 +31,7 @@ You are an AI writing assistant specialized in creating exceptional technical do- Use descriptive, keyword-rich headings for navigation and SEO### User-centered approach+- Focus on user goals and outcomes rather than system features- Anticipate common questions and address them proactively- Include troubleshooting for likely failure points@@ -73,11 +77,11 @@ Positive confirmations, successful completions, or achievement indicators```javascript config.jsconst apiConfig = {-baseURL: 'https://api.example.com',-timeout: 5000,-headers: {- 'Authorization': `Bearer ${process.env.API_TOKEN}`-}+ baseURL: "https://api.example.com",+ timeout: 5000,+ headers: {+ Authorization: `Bearer ${process.env.API_TOKEN}`,+ },};```@@ -92,7 +96,7 @@ const response = await fetch('/api/endpoint', {```python Pythonimport requests-response = requests.get('/api/endpoint',+response = requests.get('/api/endpoint',headers={'Authorization': f'Bearer {api_key}'})```@@ -100,6 +104,7 @@ response = requests.get('/api/endpoint',curl -X GET '/api/endpoint' \-H 'Authorization: Bearer YOUR_API_KEY'```+</CodeGroup>#### Request/Response examples@@ -293,9 +298,10 @@ API- Improved error messages with actionable suggestions## Bug fixes+- Fixed pagination issue with large datasets- Resolved authentication timeout problems-</Update>+ </Update>## Required page structure@@ -311,6 +317,7 @@ description: "Concise description explaining page purpose and value"## Content quality standards### Code examples requirements+- Always include complete, runnable examples that users can copy and execute- Show proper error handling and edge case management- Use realistic data instead of placeholder values@@ -320,6 +327,7 @@ description: "Concise description explaining page purpose and value"- Add explanatory comments for complex logic### API documentation requirements+- Document all parameters including optional ones with clear descriptions- Show both success and error response examples with realistic data- Include rate limiting information with specific limits@@ -327,7 +335,36 @@ description: "Concise description explaining page purpose and value"- Explain all HTTP status codes and error handling- Cover complete request/response cycles+### Adding new API endpoints++When adding a new API endpoint to the documentation, you must update multiple files to ensure consistency across the documentation system:++1. **Create or update the MDX documentation file** (`docs/api-reference/{category}/{endpoint-name}.mdx`):+ - Create a new MDX file in the appropriate category directory (e.g., `forms/`, `workspaces/`, `submissions/`)+ - Include the OpenAPI reference in the frontmatter: `openapi: {method} {path}`+ - Follow the standard structure: Authentication & Scope, Request, Response sections+ - Include all path parameters, query parameters, and request/response examples++2. **Update the navigation** (`docs/docs.json`):+ - Add the new page path to the appropriate group in the API Reference section+ - Maintain logical ordering (CRUD operations: list, create, get, update, delete)+ - Place deprecated endpoints after their replacements++3. **Update the OpenAPI specification** (`docs/api-reference/openapi.yaml`):+ - Add the endpoint definition under the `paths` section+ - Include complete parameter definitions, request body schemas, and response schemas+ - Use appropriate tags to categorize the endpoint+ - Mark deprecated endpoints with `deprecated: true` flag+ - Ensure response schemas reference existing components or define new ones++4. **Enable token authentication** (if applicable):+ - Add the route name to `api/config/sanctum-routes.php` if the endpoint should be accessible via Personal Access Tokens+ - Use the exact route name as defined in the Laravel routes file (e.g., `open.workspaces.forms.index`)++Example workflow: When adding a new workspace forms endpoint, you would create `docs/api-reference/forms/list-workspace-forms.mdx`, add it to the Forms group in `docs.json`, add the path definition to `openapi.yaml`, and add the route to `sanctum-routes.php` if needed.+### Accessibility requirements+- Include descriptive alt text for all images and diagrams- Use specific, actionable link text instead of "click here"- Ensure proper heading hierarchy starting with H2@@ -338,6 +375,7 @@ description: "Concise description explaining page purpose and value"## AI assistant instructions### Component selection logic+- Use **Steps** for procedures, tutorials, setup guides, and sequential instructions- Use **Tabs** for platform-specific content or alternative approaches- Use **CodeGroup** when showing the same concept in multiple languages@@ -348,6 +386,7 @@ description: "Concise description explaining page purpose and value"- Use **Expandable** for nested object properties or hierarchical information### Quality assurance checklist+- Verify all code examples are syntactically correct and executable- Test all links to ensure they are functional and lead to relevant content- Validate Mintlify component syntax with all required properties@@ -356,9 +395,10 @@ description: "Concise description explaining page purpose and value"- Check for consistency in terminology, formatting, and component usage### Error prevention strategies+- Always include realistic error handling in code examples- Provide dedicated troubleshooting sections for complex procedures- Explain prerequisites clearly before beginning instructions- Include verification and testing steps with expected outcomes- Add appropriate warnings for destructive or security-sensitive actions-- Validate all technical information through testing before publication\ No newline at end of file+- Validate all technical information through testing before publicationdiff --git a/api/config/sanctum-routes.php b/api/config/sanctum-routes.phpindex e82840cc9..c9cfde952 100644--- a/api/config/sanctum-routes.php+++ b/api/config/sanctum-routes.php@@ -27,6 +27,7 @@ return ['open.workspaces.create','open.workspaces.update','open.workspaces.delete',+ 'open.workspaces.forms.index',// Workspace User Management'open.workspaces.users.index',diff --git a/docs/api-reference/forms/list-forms.mdx b/docs/api-reference/forms/list-forms.mdxindex fc7c0f410..03ed8d69f 100644--- a/docs/api-reference/forms/list-forms.mdx+++ b/docs/api-reference/forms/list-forms.mdx@@ -2,7 +2,11 @@openapi: get /open/forms----# List Forms+# List Forms (Deprecated)++<Warning>+**Deprecated**: This endpoint is deprecated. Use [List Workspace Forms](./list-workspace-forms) instead to retrieve forms for a specific workspace.+</Warning>Retrieve every form accessible to the authenticated user across **all** of their workspaces.diff --git a/docs/api-reference/forms/list-workspace-forms.mdx b/docs/api-reference/forms/list-workspace-forms.mdxnew file mode 100644index 000000000..edfc936ca--- /dev/null+++ b/docs/api-reference/forms/list-workspace-forms.mdx@@ -0,0 +1,62 @@+---+openapi: get /open/workspaces/{workspaceId}/forms+---++Retrieve all forms within a specific workspace.++## Authentication & Scope++This request must be authenticated using a **Personal Access Token** that includes the `forms-read` ability.++```http+Authorization: Bearer <token>+```++## Request++```http+GET /open/workspaces/{workspaceId}/forms HTTP/1.1+Host: api.opnform.com+Authorization: Bearer <token>+```++### Path Parameters++| Parameter | Type | Description |+|-------------|--------|----------------------------------|+| workspaceId | number | ID of the workspace to retrieve forms from. |++### Query Parameters++| Parameter | Type | Description | Default |+|-----------|--------|------------------------------------------------|---------|+| page | number | Page number for pagination. | 1 |++## Response++`200 OK` – Returns a paginated JSON response containing Form objects.++```json+{+ "data": [+ {+ "id": 42,+ "slug": "customer-feedback",+ "title": "Customer Feedback",+ "visibility": "public",+ "submissions_count": 15,+ "properties": [+ /* form fields & layout blocks */+ ]+ }+ ],+ "current_page": 1,+ "per_page": 10,+ "total": 1+}+```++`403 Forbidden` – The token does not include the required `forms-read` ability, or you do not have access to the workspace.++`404 Not Found` – The workspace does not exist.+diff --git a/docs/api-reference/openapi.yaml b/docs/api-reference/openapi.yamlindex 95151a724..9f417b38a 100644--- a/docs/api-reference/openapi.yaml+++ b/docs/api-reference/openapi.yaml@@ -362,12 +362,80 @@ paths:example: Invite deleted successfully."403":description: Forbidden+ "/open/workspaces/{workspaceId}/forms":+ get:+ tags:+ - Forms+ summary: List Workspace Forms+ description: "Retrieve all forms within a specific workspace. Requires `forms-read` ability."+ security:+ - bearerAuth: []+ parameters:+ - name: workspaceId+ in: path+ required: true+ schema:+ type: number+ description: ID of the workspace to retrieve forms from.+ - name: page+ in: query+ required: false+ schema:+ type: number+ minimum: 1+ default: 1+ description: "Pagination page number"+ responses:+ "200":+ description: Successful+ content:+ application/json:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ $ref: "#/components/schemas/Form"+ links:+ type: object+ properties:+ first:+ type: string+ last:+ type: string+ prev:+ type: string+ nullable: true+ next:+ type: string+ nullable: true+ meta:+ type: object+ properties:+ current_page:+ type: number+ from:+ type: number+ last_page:+ type: number+ per_page:+ type: number+ to:+ type: number+ total:+ type: number+ "403":+ description: "Forbidden – token lacks forms-read ability or you do not have access to the workspace"+ "404":+ description: "Workspace not found""/open/forms":get:tags:- Formssummary: List Forms- description: Retrieve all forms accessible to the token holder.+ description: "Retrieve all forms accessible to the token holder across all workspaces. **Deprecated**: Use `/open/workspaces/{workspaceId}/forms` instead."+ deprecated: truesecurity:- bearerAuth: []responses:diff --git a/docs/docs.json b/docs/docs.jsonindex 679ce9b8f..e4b17a898 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -62,22 +62,10 @@"api-reference/workspaces/delete-workspace"]},- {- "group": "Workspace Users",- "pages": [- "api-reference/workspace-users/list-workspace-users",- "api-reference/workspace-users/list-workspace-invites",- "api-reference/workspace-users/add-workspace-user",- "api-reference/workspace-users/remove-workspace-user",- "api-reference/workspace-users/update-workspace-user-role",- "api-reference/workspace-users/leave-workspace",- "api-reference/workspace-users/resend-workspace-invite",- "api-reference/workspace-users/cancel-workspace-invite"- ]- },{"group": "Forms","pages": [+ "api-reference/forms/list-workspace-forms","api-reference/forms/list-forms","api-reference/forms/create-form","api-reference/forms/get-form",@@ -106,6 +94,19 @@"api-reference/integrations/list-webhook-events"]},+ {+ "group": "Workspace Users",+ "pages": [+ "api-reference/workspace-users/list-workspace-users",+ "api-reference/workspace-users/list-workspace-invites",+ "api-reference/workspace-users/add-workspace-user",+ "api-reference/workspace-users/remove-workspace-user",+ "api-reference/workspace-users/update-workspace-user-role",+ "api-reference/workspace-users/leave-workspace",+ "api-reference/workspace-users/resend-workspace-invite",+ "api-reference/workspace-users/cancel-workspace-invite"+ ]+ },{"group": "Zapier","pages": [