Generations API – POST /api/generate-swagger-api

This endpoint generates a Swagger/OpenAPI JSON specification from provided source code. It leverages DocuWriter.ai’s backend to invoke an LLM, synthesize API metadata, persist the result, and return a ready-to-use OpenAPI 3.x document.

🛡️ Authentication

All requests must include a valid API token.

• Header: Authorization: Bearer

Only authenticated users with non-Viewer roles and available credits may proceed.

🔑 Request Parameters

{
  "source_code": "string",                // Required: Full code text to document
  "filename": "string",                   // Required: Original file name
  "additional_instructions": "string"     // Optional: LLM prompt tweaks
}

• source_code: Must be a non-empty string.
• filename: Used in prompts and record creation.
• additional_instructions: Appended verbatim to LLM prompt.

⚙️ Rate & Size Limits

• Credit check

💼 Role Enforcement

Users with the Viewer role cannot generate API docs. They receive:

HTTP 403
{
  "success": false,
  "message": "Users with the Viewer role cannot generate API documentation."
}

🧰 Interactive API Block

{
    "title": "Generate Swagger API Documentation",
    "description": "Generate OpenAPI JSON from source code via LLM.",
    "method": "POST",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/generate-swagger-api",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n  \"source_code\": \"<your code>\",\n  \"filename\": \"MyController.php\",\n  \"additional_instructions\": \"Add bearerAuth globally.\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n  \"success\": true,\n  \"data\": {\n    \"generation\": \"{...Swagger JSON...}\",\n    \"generation_id\": 42\n  }\n}"
        },
        "400": {
            "description": "Validation or size error",
            "body": "{\n  \"success\": false,\n  \"message\": \"The provided code is too large for processing. Please reduce the amount of code and try again.\"\n}"
        },
        "403": {
            "description": "Role or credit restriction",
            "body": "{\n  \"success\": false,\n  \"message\": \"Users with the Viewer role cannot generate API documentation.\"\n}"
        },
        "500": {
            "description": "Server or LLM error",
            "body": "{\n  \"success\": false,\n  \"message\": \"There was an error generating the API documentation. Please try again.\"\n}"
        }
    }
}