create-specra 0.1.0

package/templates/minimal/public/api-specs/test-api.json

@@ -0,0 +1,256 @@
+{
+  "version": "1.0.0",
+  "title": "Test API",
+  "description": "A simple test API for demonstrating the API documentation system",
+  "baseUrl": "https://jsonplaceholder.typicode.com",
+  "auth": {
+    "type": "apiKey",
+    "description": "This is a public API - no authentication required for testing",
+    "headerName": "X-API-Key"
+  },
+  "endpoints": [
+    {
+      "title": "Get All Posts",
+      "method": "GET",
+      "path": "/posts",
+      "description": "Retrieve a list of all blog posts",
+      "queryParams": [
+        {
+          "name": "_limit",
+          "type": "number",
+          "description": "Limit the number of results",
+          "example": 5
+        },
+        {
+          "name": "userId",
+          "type": "number",
+          "description": "Filter posts by user ID",
+          "example": 1
+        }
+      ],
+      "successResponse": {
+        "status": 200,
+        "description": "List of posts retrieved successfully",
+        "example": [
+          {
+            "userId": 1,
+            "id": 1,
+            "title": "sunt aut facere repellat provident",
+            "body": "quia et suscipit..."
+          },
+          {
+            "userId": 1,
+            "id": 2,
+            "title": "qui est esse",
+            "body": "est rerum tempore vitae..."
+          }
+        ]
+      },
+      "examples": [
+        {
+          "title": "cURL",
+          "language": "bash",
+          "code": "curl https://jsonplaceholder.typicode.com/posts?_limit=5"
+        },
+        {
+          "title": "JavaScript",
+          "language": "javascript",
+          "code": "const response = await fetch('https://jsonplaceholder.typicode.com/posts?_limit=5');\nconst posts = await response.json();\nconsole.log(posts);"
+        },
+        {
+          "title": "Python",
+          "language": "python",
+          "code": "import requests\n\nresponse = requests.get('https://jsonplaceholder.typicode.com/posts', params={'_limit': 5})\nposts = response.json()\nprint(posts)"
+        }
+      ]
+    },
+    {
+      "title": "Get Post by ID",
+      "method": "GET",
+      "path": "/posts/:id",
+      "description": "Retrieve a single post by its ID",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "number",
+          "required": true,
+          "description": "The ID of the post to retrieve",
+          "example": 1
+        }
+      ],
+      "successResponse": {
+        "status": 200,
+        "description": "Post retrieved successfully",
+        "example": {
+          "userId": 1,
+          "id": 1,
+          "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
+          "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
+        }
+      },
+      "errorResponses": [
+        {
+          "status": 404,
+          "description": "Post not found",
+          "example": {}
+        }
+      ]
+    },
+    {
+      "title": "Create New Post",
+      "method": "POST",
+      "path": "/posts",
+      "description": "Create a new blog post",
+      "body": {
+        "description": "Post data to create",
+        "example": {
+          "title": "My New Post",
+          "body": "This is the content of my new post",
+          "userId": 1
+        }
+      },
+      "successResponse": {
+        "status": 201,
+        "description": "Post created successfully",
+        "example": {
+          "id": 101,
+          "title": "My New Post",
+          "body": "This is the content of my new post",
+          "userId": 1
+        }
+      },
+      "examples": [
+        {
+          "title": "cURL",
+          "language": "bash",
+          "code": "curl -X POST https://jsonplaceholder.typicode.com/posts \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"title\": \"My New Post\",\n    \"body\": \"This is the content\",\n    \"userId\": 1\n  }'"
+        },
+        {
+          "title": "JavaScript",
+          "language": "javascript",
+          "code": "const response = await fetch('https://jsonplaceholder.typicode.com/posts', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    title: 'My New Post',\n    body: 'This is the content',\n    userId: 1\n  })\n});\nconst post = await response.json();\nconsole.log(post);"
+        }
+      ]
+    },
+    {
+      "title": "Update Post",
+      "method": "PUT",
+      "path": "/posts/:id",
+      "description": "Update an existing post (replaces all fields)",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "number",
+          "required": true,
+          "description": "The ID of the post to update",
+          "example": 1
+        }
+      ],
+      "body": {
+        "description": "Complete post data",
+        "example": {
+          "id": 1,
+          "title": "Updated Title",
+          "body": "Updated content",
+          "userId": 1
+        }
+      },
+      "successResponse": {
+        "status": 200,
+        "description": "Post updated successfully",
+        "example": {
+          "id": 1,
+          "title": "Updated Title",
+          "body": "Updated content",
+          "userId": 1
+        }
+      }
+    },
+    {
+      "title": "Partially Update Post",
+      "method": "PATCH",
+      "path": "/posts/:id",
+      "description": "Partially update a post (only updates provided fields)",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "number",
+          "required": true,
+          "description": "The ID of the post to update",
+          "example": 1
+        }
+      ],
+      "body": {
+        "description": "Fields to update (all optional)",
+        "example": {
+          "title": "New Title Only"
+        }
+      },
+      "successResponse": {
+        "status": 200,
+        "description": "Post updated successfully",
+        "example": {
+          "userId": 1,
+          "id": 1,
+          "title": "New Title Only",
+          "body": "quia et suscipit..."
+        }
+      }
+    },
+    {
+      "title": "Delete Post",
+      "method": "DELETE",
+      "path": "/posts/:id",
+      "description": "Delete a post",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "number",
+          "required": true,
+          "description": "The ID of the post to delete",
+          "example": 1
+        }
+      ],
+      "successResponse": {
+        "status": 200,
+        "description": "Post deleted successfully",
+        "example": {}
+      }
+    },
+    {
+      "title": "Get Comments for Post",
+      "method": "GET",
+      "path": "/posts/:id/comments",
+      "description": "Retrieve all comments for a specific post",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "number",
+          "required": true,
+          "description": "The post ID",
+          "example": 1
+        }
+      ],
+      "successResponse": {
+        "status": 200,
+        "description": "Comments retrieved successfully",
+        "example": [
+          {
+            "postId": 1,
+            "id": 1,
+            "name": "id labore ex et quam laborum",
+            "email": "Eliseo@gardner.biz",
+            "body": "laudantium enim quasi est quidem magnam..."
+          },
+          {
+            "postId": 1,
+            "id": 2,
+            "name": "quo vero reiciendis velit similique earum",
+            "email": "Jayne_Kuhic@sydney.com",
+            "body": "est natus enim nihil est dolore omnis..."
+          }
+        ]
+      }
+    }
+  ]
+}

package/templates/minimal/public/api-specs/users-api.json

@@ -0,0 +1,264 @@
+{
+  "version": "1.0.0",
+  "title": "Users API",
+  "description": "Complete API reference for managing users in the system",
+  "baseUrl": "https://api.example.com/v1",
+  "env": {
+    "AUTH_TOKEN": "your_api_token_here"
+  },
+  "auth": {
+    "type": "bearer",
+    "description": "All requests require a valid API token in the Authorization header",
+    "tokenPrefix": "Bearer"
+  },
+  "globalHeaders": [
+    {
+      "name": "Authorization",
+      "value": "Bearer {AUTH_TOKEN}",
+      "description": "Your API authentication token"
+    },
+    {
+      "name": "Content-Type",
+      "value": "application/json"
+    }
+  ],
+  "endpoints": [
+    {
+      "title": "Get User by ID",
+      "method": "GET",
+      "path": "/users/:id",
+      "description": "Retrieve detailed information about a specific user",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "The unique identifier of the user",
+          "example": "user_123"
+        }
+      ],
+      "queryParams": [
+        {
+          "name": "fields",
+          "type": "string",
+          "description": "Comma-separated list of fields to include",
+          "example": "name,email,created_at"
+        },
+        {
+          "name": "include_metadata",
+          "type": "boolean",
+          "description": "Include additional metadata in the response",
+          "default": false
+        }
+      ],
+      "successResponse": {
+        "status": 200,
+        "description": "User retrieved successfully",
+        "example": {
+          "id": "user_123",
+          "name": "John Doe",
+          "email": "john@example.com",
+          "role": "admin",
+          "created_at": "2024-01-15T10:30:00Z",
+          "updated_at": "2024-01-20T14:22:00Z"
+        }
+      },
+      "errorResponses": [
+        {
+          "status": 404,
+          "description": "User not found",
+          "example": {
+            "error": "User not found",
+            "code": "USER_NOT_FOUND",
+            "message": "No user exists with the provided ID"
+          }
+        },
+        {
+          "status": 401,
+          "description": "Unauthorized",
+          "example": {
+            "error": "Unauthorized",
+            "code": "UNAUTHORIZED",
+            "message": "Invalid or missing authentication token"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "cURL",
+          "language": "bash",
+          "code": "curl -X GET \"https://api.example.com/v1/users/user_123\" \\\n  -H \"Authorization: Bearer your_api_token_here\""
+        },
+        {
+          "title": "JavaScript (fetch)",
+          "language": "javascript",
+          "code": "const response = await fetch('https://api.example.com/v1/users/user_123', {\n  headers: {\n    'Authorization': 'Bearer your_api_token_here'\n  }\n});\nconst user = await response.json();"
+        }
+      ]
+    },
+    {
+      "title": "List All Users",
+      "method": "GET",
+      "path": "/users",
+      "description": "Retrieve a paginated list of all users",
+      "queryParams": [
+        {
+          "name": "page",
+          "type": "number",
+          "description": "Page number for pagination",
+          "default": 1
+        },
+        {
+          "name": "limit",
+          "type": "number",
+          "description": "Number of users per page",
+          "default": 20
+        },
+        {
+          "name": "role",
+          "type": "string",
+          "description": "Filter users by role",
+          "example": "admin"
+        }
+      ],
+      "successResponse": {
+        "status": 200,
+        "description": "List of users retrieved successfully",
+        "example": {
+          "data": [
+            {
+              "id": "user_123",
+              "name": "John Doe",
+              "email": "john@example.com",
+              "role": "admin"
+            },
+            {
+              "id": "user_124",
+              "name": "Jane Smith",
+              "email": "jane@example.com",
+              "role": "user"
+            }
+          ],
+          "pagination": {
+            "page": 1,
+            "limit": 20,
+            "total": 42,
+            "pages": 3
+          }
+        }
+      }
+    },
+    {
+      "title": "Create New User",
+      "method": "POST",
+      "path": "/users",
+      "description": "Create a new user account",
+      "body": {
+        "description": "User data to create",
+        "example": {
+          "name": "Alice Johnson",
+          "email": "alice@example.com",
+          "role": "user",
+          "password": "secure_password_123"
+        }
+      },
+      "successResponse": {
+        "status": 201,
+        "description": "User created successfully",
+        "example": {
+          "id": "user_125",
+          "name": "Alice Johnson",
+          "email": "alice@example.com",
+          "role": "user",
+          "created_at": "2024-01-21T09:15:00Z"
+        }
+      },
+      "errorResponses": [
+        {
+          "status": 400,
+          "description": "Validation error",
+          "example": {
+            "error": "Validation failed",
+            "code": "VALIDATION_ERROR",
+            "details": {
+              "email": "Email address already exists"
+            }
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "cURL",
+          "language": "bash",
+          "code": "curl -X POST \"https://api.example.com/v1/users\" \\\n  -H \"Authorization: Bearer your_api_token_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Alice Johnson\",\n    \"email\": \"alice@example.com\",\n    \"role\": \"user\",\n    \"password\": \"secure_password_123\"\n  }'"
+        }
+      ]
+    },
+    {
+      "title": "Update User",
+      "method": "PATCH",
+      "path": "/users/:id",
+      "description": "Update user information",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "User ID to update"
+        }
+      ],
+      "body": {
+        "description": "Fields to update (all optional)",
+        "example": {
+          "name": "John Updated",
+          "email": "john.updated@example.com",
+          "role": "moderator"
+        }
+      },
+      "successResponse": {
+        "status": 200,
+        "description": "User updated successfully",
+        "example": {
+          "id": "user_123",
+          "name": "John Updated",
+          "email": "john.updated@example.com",
+          "role": "moderator",
+          "updated_at": "2024-01-21T10:00:00Z"
+        }
+      }
+    },
+    {
+      "title": "Delete User",
+      "method": "DELETE",
+      "path": "/users/:id",
+      "description": "Permanently delete a user account",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "User ID to delete"
+        }
+      ],
+      "successResponse": {
+        "status": 204,
+        "description": "User deleted successfully"
+      },
+      "errorResponses": [
+        {
+          "status": 404,
+          "description": "User not found"
+        },
+        {
+          "status": 403,
+          "description": "Forbidden - Cannot delete this user",
+          "example": {
+            "error": "Forbidden",
+            "code": "CANNOT_DELETE_ADMIN",
+            "message": "Cannot delete the primary admin account"
+          }
+        }
+      ]
+    }
+  ]
+}

package/templates/minimal/scripts/generate-redirects.mjs

@@ -0,0 +1,88 @@
+import fs from "fs"
+import path from "path"
+import matter from "gray-matter"
+import { fileURLToPath } from "url"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const DOCS_DIR = path.join(__dirname, "..", "docs")
+
+/**
+ * Recursively find all MDX files
+ */
+function findMdxFiles(dir, baseDir = dir) {
+  const files = []
+
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        files.push(...findMdxFiles(fullPath, baseDir))
+      } else if (entry.isFile() && entry.name.endsWith(".mdx")) {
+        const relativePath = path.relative(baseDir, fullPath)
+        files.push(relativePath)
+      }
+    }
+  } catch (error) {
+    console.error(`Error reading directory ${dir}:`, error)
+  }
+
+  return files
+}
+
+/**
+ * Build redirect mappings from frontmatter
+ */
+async function buildRedirects() {
+  const versions = fs.readdirSync(DOCS_DIR).filter((v) => {
+    const stat = fs.statSync(path.join(DOCS_DIR, v))
+    return stat.isDirectory()
+  })
+
+  const redirects = []
+
+  for (const version of versions) {
+    const versionDir = path.join(DOCS_DIR, version)
+    const mdxFiles = findMdxFiles(versionDir)
+
+    for (const file of mdxFiles) {
+      const filePath = path.join(versionDir, file)
+      const fileContents = fs.readFileSync(filePath, "utf8")
+      const { data } = matter(fileContents)
+
+      if (data.redirect_from && Array.isArray(data.redirect_from)) {
+        const slug = file.replace(/\.mdx$/, "")
+        const destination = `/docs/${version}/${slug}`
+
+        for (const source of data.redirect_from) {
+          redirects.push({
+            source,
+            destination,
+            permanent: true,
+          })
+        }
+      }
+    }
+  }
+
+  return redirects
+}
+
+/**
+ * Generate redirects and write to a JSON file
+ */
+async function main() {
+  const redirects = await buildRedirects()
+  
+  const outputPath = path.join(__dirname, "..", "redirects.json")
+  fs.writeFileSync(outputPath, JSON.stringify(redirects, null, 2))
+  
+  console.log(`✅ Generated ${redirects.length} redirects`)
+  console.log(`📝 Saved to: ${outputPath}`)
+}
+
+main().catch(console.error)