openclawd/docfast
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

v0.4.1: Code-driven OpenAPI docs via swagger-jsdoc
Some checks failed
Build & Deploy to Staging / Build & Deploy to Staging (push) Has been cancelled
Details

Browse source 
- Add swagger-jsdoc dependency for auto-generating OpenAPI spec from JSDoc
- Add JSDoc @openapi annotations to all route handlers
- Create scripts/generate-openapi.mjs build step
- OpenAPI spec now auto-generated from code — no manual JSON editing
- All 13 endpoints documented with full parameters
- New demo endpoints documented, signup marked as deprecated
- Updated info description: demo-first, no free tier references
- Dockerfile updated to run openapi generation during build
- Build script updated: npm run build generates spec before compile
This commit is contained in:
DocFast Bot 2026-02-20 07:54:37 +00:00
parent 53755d6093
commit 792e2d9142
12 changed files with 1931 additions and 305 deletions
Download patch file Download diff file Expand all files Collapse all files

63
src/openapi-extra.yaml Normal file
View file

@ -0,0 +1,63 @@
paths:
/v1/signup/free:
post:
tags:
- Account
summary: Free signup (discontinued)
description: |
Free accounts have been discontinued. Use the demo endpoint for testing
or subscribe to Pro for production use.
deprecated: true
requestBody:
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
responses:
'410':
description: Free accounts discontinued
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: 'Free accounts have been discontinued.'
demo_endpoint:
type: string
example: '/v1/demo/html'
pro_url:
type: string
example: 'https://docfast.dev/#pricing'
/v1/usage:
get:
tags:
- System
summary: Usage statistics (admin only)
description: Returns usage statistics for the authenticated user. Requires admin API key.
security:
- BearerAuth: []
- ApiKeyHeader: []
responses:
'200':
description: Usage statistics
content:
application/json:
schema:
type: object
additionalProperties:
type: object
properties:
count:
type: integer
month:
type: string
'403':
description: Admin access required
'503':
description: Admin access not configured

30
src/routes/billing.ts
View file

@ -56,7 +56,35 @@ const checkoutLimiter = rateLimit({
message: { error: "Too many checkout requests. Please try again later." },
});
// Create a Stripe Checkout session for Pro subscription
/**
* @openapi
* /v1/billing/checkout:
* post:
* tags: [Billing]
* summary: Create a Stripe checkout session
* description: |
* Creates a Stripe Checkout session for a Pro subscription (€9/month).
* Returns a URL to redirect the user to Stripe's hosted payment page.
* Rate limited to 3 requests per hour per IP.
* responses:
* 200:
* description: Checkout session created
* content:
* application/json:
* schema:
* type: object
* properties:
* url:
* type: string
* format: uri
* description: Stripe Checkout URL to redirect the user to
* 413:
* description: Request body too large
* 429:
* description: Too many checkout requests
* 500:
* description: Failed to create checkout session
*/
router.post("/checkout", checkoutLimiter, async (req: Request, res: Response) => {
// Reject suspiciously large request bodies (>1KB)
const contentLength = parseInt(req.headers["content-length"] || "0", 10);

153
src/routes/convert.ts
View file

@ -49,7 +49,55 @@ interface ConvertBody {
filename?: string;
}
// POST /v1/convert/html
/**
* @openapi
* /v1/convert/html:
* post:
* tags: [Conversion]
* summary: Convert HTML to PDF
* description: Converts HTML content to a PDF document. Bare HTML fragments are automatically wrapped in a full HTML document.
* security:
* - BearerAuth: []
* - ApiKeyHeader: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* allOf:
* - type: object
* required: [html]
* properties:
* html:
* type: string
* description: HTML content to convert. Can be a full document or a fragment.
* example: '<h1>Hello World</h1><p>My first PDF</p>'
* css:
* type: string
* description: Optional CSS to inject (only used when html is a fragment, not a full document)
* example: 'body { font-family: sans-serif; padding: 40px; }'
* - $ref: '#/components/schemas/PdfOptions'
* responses:
* 200:
* description: PDF document
* content:
* application/pdf:
* schema:
* type: string
* format: binary
* 400:
* description: Missing html field
* 401:
* description: Missing API key
* 403:
* description: Invalid API key
* 415:
* description: Unsupported Content-Type (must be application/json)
* 429:
* description: Rate limit or usage limit exceeded
* 500:
* description: PDF generation failed
*/
convertRouter.post("/html", async (req: Request & { acquirePdfSlot?: () => Promise<void>; releasePdfSlot?: () => void }, res: Response) => {
let slotAcquired = false;
try {
@ -103,7 +151,54 @@ convertRouter.post("/html", async (req: Request & { acquirePdfSlot?: () => Promi
}
});
// POST /v1/convert/markdown
/**
* @openapi
* /v1/convert/markdown:
* post:
* tags: [Conversion]
* summary: Convert Markdown to PDF
* description: Converts Markdown content to HTML and then to a PDF document.
* security:
* - BearerAuth: []
* - ApiKeyHeader: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* allOf:
* - type: object
* required: [markdown]
* properties:
* markdown:
* type: string
* description: Markdown content to convert
* example: '# Hello World\n\nThis is **bold** and *italic*.'
* css:
* type: string
* description: Optional CSS to inject into the rendered HTML
* - $ref: '#/components/schemas/PdfOptions'
* responses:
* 200:
* description: PDF document
* content:
* application/pdf:
* schema:
* type: string
* format: binary
* 400:
* description: Missing markdown field
* 401:
* description: Missing API key
* 403:
* description: Invalid API key
* 415:
* description: Unsupported Content-Type
* 429:
* description: Rate limit or usage limit exceeded
* 500:
* description: PDF generation failed
*/
convertRouter.post("/markdown", async (req: Request & { acquirePdfSlot?: () => Promise<void>; releasePdfSlot?: () => void }, res: Response) => {
let slotAcquired = false;
try {
@ -153,7 +248,59 @@ convertRouter.post("/markdown", async (req: Request & { acquirePdfSlot?: () => P
}
});
// POST /v1/convert/url
/**
* @openapi
* /v1/convert/url:
* post:
* tags: [Conversion]
* summary: Convert URL to PDF
* description: |
* Fetches a URL and converts the rendered page to PDF. JavaScript is disabled for security.
* Private/internal IP addresses are blocked (SSRF protection). DNS is pinned to prevent rebinding.
* security:
* - BearerAuth: []
* - ApiKeyHeader: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* allOf:
* - type: object
* required: [url]
* properties:
* url:
* type: string
* format: uri
* description: URL to convert (http or https only)
* example: 'https://example.com'
* waitUntil:
* type: string
* enum: [load, domcontentloaded, networkidle0, networkidle2]
* default: domcontentloaded
* description: When to consider navigation finished
* - $ref: '#/components/schemas/PdfOptions'
* responses:
* 200:
* description: PDF document
* content:
* application/pdf:
* schema:
* type: string
* format: binary
* 400:
* description: Missing/invalid URL or URL resolves to private IP
* 401:
* description: Missing API key
* 403:
* description: Invalid API key
* 415:
* description: Unsupported Content-Type
* 429:
* description: Rate limit or usage limit exceeded
* 500:
* description: PDF generation failed
*/
convertRouter.post("/url", async (req: Request & { acquirePdfSlot?: () => Promise<void>; releasePdfSlot?: () => void }, res: Response) => {
let slotAcquired = false;
try {

100
src/routes/demo.ts
View file

@ -42,7 +42,59 @@ function sanitizeFilename(name: string): string {
return name.replace(/[\x00-\x1f"\\\r\n]/g, "").trim() || "document.pdf";
}
// POST /v1/demo/html
/**
* @openapi
* /v1/demo/html:
* post:
* tags: [Demo]
* summary: Convert HTML to PDF (demo)
* description: |
* Public endpoint — no API key required. Rate limited to 5 requests per hour per IP.
* Output PDFs include a DocFast watermark. Upgrade to Pro for clean output.
* requestBody:
* required: true
* content:
* application/json:
* schema:
* allOf:
* - type: object
* required: [html]
* properties:
* html:
* type: string
* description: HTML content to convert
* example: '<h1>Hello World</h1><p>My first PDF</p>'
* css:
* type: string
* description: Optional CSS to inject (used when html is a fragment)
* - $ref: '#/components/schemas/PdfOptions'
* responses:
* 200:
* description: Watermarked PDF document
* content:
* application/pdf:
* schema:
* type: string
* format: binary
* 400:
* description: Missing html field
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
* 415:
* description: Unsupported Content-Type
* 429:
* description: Demo rate limit exceeded (5/hour)
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
* 503:
* description: Server busy
* 504:
* description: PDF generation timed out
*/
router.post("/html", async (req: Request & { acquirePdfSlot?: () => Promise<void>; releasePdfSlot?: () => void }, res: Response) => {
let slotAcquired = false;
try {
@ -93,7 +145,51 @@ router.post("/html", async (req: Request & { acquirePdfSlot?: () => Promise<void
}
});
// POST /v1/demo/markdown
/**
* @openapi
* /v1/demo/markdown:
* post:
* tags: [Demo]
* summary: Convert Markdown to PDF (demo)
* description: |
* Public endpoint — no API key required. Rate limited to 5 requests per hour per IP.
* Markdown is converted to HTML then rendered to PDF with a DocFast watermark.
* requestBody:
* required: true
* content:
* application/json:
* schema:
* allOf:
* - type: object
* required: [markdown]
* properties:
* markdown:
* type: string
* description: Markdown content to convert
* example: '# Hello World\n\nThis is **bold** and *italic*.'
* css:
* type: string
* description: Optional CSS to inject
* - $ref: '#/components/schemas/PdfOptions'
* responses:
* 200:
* description: Watermarked PDF document
* content:
* application/pdf:
* schema:
* type: string
* format: binary
* 400:
* description: Missing markdown field
* 415:
* description: Unsupported Content-Type
* 429:
* description: Demo rate limit exceeded (5/hour)
* 503:
* description: Server busy
* 504:
* description: PDF generation timed out
*/
router.post("/markdown", async (req: Request & { acquirePdfSlot?: () => Promise<void>; releasePdfSlot?: () => void }, res: Response) => {
let slotAcquired = false;
try {

50
src/routes/health.ts
View file

@ -10,6 +10,56 @@ export const healthRouter = Router();
const HEALTH_CHECK_TIMEOUT_MS = 3000;
/**
* @openapi
* /health:
* get:
* tags: [System]
* summary: Health check
* description: Returns service health status including database connectivity and browser pool stats.
* responses:
* 200:
* description: Service is healthy
* content:
* application/json:
* schema:
* type: object
* properties:
* status:
* type: string
* enum: [ok, degraded]
* version:
* type: string
* example: '0.4.0'
* database:
* type: object
* properties:
* status:
* type: string
* enum: [ok, error]
* version:
* type: string
* example: 'PostgreSQL 17.4'
* pool:
* type: object
* properties:
* size:
* type: integer
* active:
* type: integer
* available:
* type: integer
* queueDepth:
* type: integer
* pdfCount:
* type: integer
* restarting:
* type: boolean
* uptimeSeconds:
* type: integer
* 503:
* description: Service is degraded (database issue)
*/
healthRouter.get("/", async (_req, res) => {
const poolStats = getPoolStats();
let databaseStatus: any;

86
src/routes/recover.ts
View file

@ -15,6 +15,46 @@ const recoverLimiter = rateLimit({
legacyHeaders: false,
});
/**
* @openapi
* /v1/recover:
* post:
* tags: [Account]
* summary: Request API key recovery
* description: |
* Sends a 6-digit verification code to the email address if an account exists.
* Response is always the same regardless of whether the email exists (to prevent enumeration).
* Rate limited to 3 requests per hour.
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required: [email]
* properties:
* email:
* type: string
* format: email
* description: Email address associated with the API key
* responses:
* 200:
* description: Recovery code sent (or no-op if email not found)
* content:
* application/json:
* schema:
* type: object
* properties:
* status:
* type: string
* example: recovery_sent
* message:
* type: string
* 400:
* description: Invalid email format
* 429:
* description: Too many recovery attempts
*/
router.post("/", recoverLimiter, async (req: Request, res: Response) => {
const { email } = req.body || {};
@ -41,6 +81,52 @@ router.post("/", recoverLimiter, async (req: Request, res: Response) => {
res.json({ status: "recovery_sent", message: "If an account exists for this email, a verification code has been sent." });
});
/**
* @openapi
* /v1/recover/verify:
* post:
* tags: [Account]
* summary: Verify recovery code and retrieve API key
* description: Verifies the 6-digit code sent via email and returns the API key if valid. Code expires after 15 minutes.
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required: [email, code]
* properties:
* email:
* type: string
* format: email
* code:
* type: string
* pattern: '^\d{6}$'
* description: 6-digit verification code
* responses:
* 200:
* description: API key recovered
* content:
* application/json:
* schema:
* type: object
* properties:
* status:
* type: string
* example: recovered
* apiKey:
* type: string
* description: The recovered API key
* tier:
* type: string
* enum: [free, pro]
* 400:
* description: Invalid verification code or missing fields
* 410:
* description: Verification code expired
* 429:
* description: Too many failed attempts
*/
router.post("/verify", recoverLimiter, async (req: Request, res: Response) => {
const { email, code } = req.body || {};

114
src/routes/templates.ts
View file

@ -9,7 +9,53 @@ function sanitizeFilename(name: string): string {
export const templatesRouter = Router();
// GET /v1/templates — list available templates
/**
* @openapi
* /v1/templates:
* get:
* tags: [Templates]
* summary: List available templates
* description: Returns a list of all built-in document templates with their required fields.
* security:
* - BearerAuth: []
* - ApiKeyHeader: []
* responses:
* 200:
* description: List of templates
* content:
* application/json:
* schema:
* type: object
* properties:
* templates:
* type: array
* items:
* type: object
* properties:
* id:
* type: string
* example: invoice
* name:
* type: string
* example: Invoice
* description:
* type: string
* fields:
* type: array
* items:
* type: object
* properties:
* name:
* type: string
* required:
* type: boolean
* description:
* type: string
* 401:
* description: Missing API key
* 403:
* description: Invalid API key
*/
templatesRouter.get("/", (_req: Request, res: Response) => {
const list = Object.entries(templates).map(([id, t]) => ({
id,
@ -20,7 +66,71 @@ templatesRouter.get("/", (_req: Request, res: Response) => {
res.json({ templates: list });
});
// POST /v1/templates/:id/render — render template to PDF
/**
* @openapi
* /v1/templates/{id}/render:
* post:
* tags: [Templates]
* summary: Render a template to PDF
* description: |
* Renders a built-in template with the provided data and returns a PDF.
* Use GET /v1/templates to see available templates and their required fields.
* Special fields: `_format` (page size), `_margin` (page margins), `_filename` (output filename).
* security:
* - BearerAuth: []
* - ApiKeyHeader: []
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: string
* description: Template ID (e.g. "invoice", "receipt")
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* data:
* type: object
* description: Template data (fields depend on template). Can also be passed at root level.
* _format:
* type: string
* enum: [A4, Letter, Legal, A3, A5, Tabloid]
* default: A4
* description: Page size override
* _margin:
* type: object
* properties:
* top: { type: string }
* right: { type: string }
* bottom: { type: string }
* left: { type: string }
* description: Page margin override
* _filename:
* type: string
* description: Custom output filename
* responses:
* 200:
* description: PDF document
* content:
* application/pdf:
* schema:
* type: string
* format: binary
* 400:
* description: Missing required template fields
* 401:
* description: Missing API key
* 403:
* description: Invalid API key
* 404:
* description: Template not found
* 500:
* description: Template rendering failed
*/
templatesRouter.post("/:id/render", async (req: Request, res: Response) => {
try {
const id = req.params.id as string;