How to Quickly Generate Laravel API Documentation Using Laravel Telescope

Generate Laravel API Documentation Using Laravel Telescope

Creating and maintaining up-to-date API documentation is one of the most important — yet often overlooked — aspects of API development. Whether you’re working on a public-facing API or an internal backend system, having proper documentation can save time, reduce onboarding challenges, and improve overall developer experience.

If you’re using Laravel, the good news is you already have powerful tools available in your ecosystem to help. One such tool is Laravel Telescope, developed and maintained by the Laravel core team.

In this blog post, we’ll explore how to use Laravel Telescope to quickly generate and analyze Laravel API request data, and how you can use this data as a foundation to build reliable and up-to-date API documentation.

⚠️ Note: Telescope does not automatically generate markdown-based API documentation (like Swagger or Postman collections), but it provides a real-time, interactive dashboard that helps developers analyze, debug, and inspect API routes — making it an invaluable tool in your API documentation workflow.

📌 What is Laravel Telescope?

Laravel Telescope is a debugging assistant and introspection tool for Laravel applications. It allows developers to monitor requests, exceptions, database queries, jobs, mails, and much more from a beautiful web UI.

Think of Telescope as a real-time window into your Laravel application’s activity, including:

HTTP requests (including API endpoints)
Response status codes
Route names and methods
Payloads (GET, POST, etc.)
Authenticated users
Exception traces

🧠 Why Use Telescope for API Documentation?

Although Laravel Telescope is not designed to generate API documentation files directly, it’s extremely useful in:

Exploring your active API routes
Viewing request/response data
Seeing real-time API usage
Identifying undocumented endpoints
Debugging API errors during development

This makes it the perfect complement to generate, review, and document your APIs quickly — especially during early development or prototyping.

🚀 How to Set Up Laravel Telescope

Let’s walk through installing and using Laravel Telescope in a Laravel API project.

Step 1: Install a New Laravel Project (Skip if You Already Have One)

composer create-project laravel/laravel laravel-api-docs
cd laravel-api-docs

Or go to your existing Laravel project.

Step 2: Install Laravel Telescope

You can install Telescope using Composer:

composer require laravel/telescope

Step 3: Publish Telescope’s Assets and Migrations

Run the following Artisan command:

php artisan telescope:install

This will publish Telescope’s configuration file (config/telescope.php) and create the necessary migration.

Run the migration:

php artisan migrate

Step 4: Serve the Application

php artisan serve

Now go to:

http://localhost:8000/telescope

You will be prompted to log in if your app uses authentication. Otherwise, Telescope will be open for viewing.

🔐 Tip: By default, Telescope is only available in the local environment for security. You can change this in config/telescope.php.

🧪 Tracking API Requests with Telescope

Let’s assume you have a few API routes defined in your app. For example:

Add Some API Routes

In routes/api.php:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::middleware('api')->get('/user', function (Request $request) {
    return ['name' => 'John Doe', 'email' => '[email protected]'];
});

Route::post('/contact', function (Request $request) {
    return response()->json([
        'message' => 'Contact form submitted successfully!',
        'data' => $request->all()
    ]);
});

Now open Postman, curl, or a browser and access:

GET http://localhost:8000/api/user
POST http://localhost:8000/api/contact

Include some JSON data with the POST request, like:

{
  "name": "Jane",
  "email": "[email protected]",
  "message": "Hi from the frontend!"
}

View API Logs in Telescope

Open the Telescope dashboard:

http://localhost:8000/telescope

Click on Requests in the left sidebar. You’ll now see a list of incoming requests including:

API endpoint (/api/user)
HTTP method (GET, POST, etc.)
Status code (e.g., 200, 404)
Duration
Timestamp

Click any row to view:

Full request headers
Request body (for POST/PUT)
Response content
Authenticated user ID (if available)
Associated route name and controller

This gives you a clear, real-time view of your API.

🧾 Using Telescope Data to Build API Documentation

Telescope’s UI acts as a live API reference explorer. You can use it to quickly collect the following for documentation:

Field	Info Extracted from Telescope
Endpoint URL	`/api/user`, `/api/contact`
Method	`GET`, `POST`, etc.
Headers	`Accept`, `Authorization`
Request Payload	JSON body for `POST` requests
Response Body	API output
Status Code	200, 201, 422, etc.

Use this information to document:

Endpoint behavior
Input requirements
Response structure
Status codes
Authentication requirements

You can then manually copy this info into Markdown files, Swagger annotations, or a Postman collection.

📋 Optional: Add Route Names for Cleaner Documentation

In routes/api.php, update your routes:

Route::get('/user', function (Request $request) {
    return ['name' => 'John Doe', 'email' => '[email protected]'];
})->name('api.user.info');

Route::post('/contact', function (Request $request) {
    return response()->json([
        'message' => 'Contact form submitted!',
        'data' => $request->all()
    ]);
})->name('api.contact.submit');

Now Telescope will display the route name alongside the endpoint, making documentation cleaner and easier to reference.

🔐 Telescope and Authentication

If your API requires authentication via Sanctum, Passport, or custom headers, Telescope will show the authenticated user under each request log.

This helps you document:

Which endpoints are protected
What tokens or headers are required

📦 Exporting Telescope Data (Optional)

Although Laravel Telescope does not export data directly, you can query its data programmatically using the database tables it stores logs in.

Telescope stores request data in the telescope_entries and telescope_entries_tags tables.

You can create a simple Artisan command or controller that fetches this data for documentation generation:

use DB;

$apiRequests = DB::table('telescope_entries')
    ->where('type', 'request')
    ->where('content', 'like', '%api/%')
    ->latest()
    ->take(50)
    ->get();

Use this to build a custom tool that auto-generates markdown or JSON documentation from live request data.

📘 Best Practices for Using Telescope for API Documentation

Here are some tips to get the most out of Laravel Telescope:

Use in Development Only
Don’t expose Telescope in production. Sensitive data like tokens and passwords may appear in logs.
Name Your Routes
Route names make API documentation more semantic and easier to read.
Use Proper Status Codes
Ensure your API returns standard HTTP codes (200, 201, 422, etc.) for clarity.
Group Routes with Prefixes
Use route groups to logically organize endpoints (e.g., /api/v1/users, /api/v1/products).
Use with Swagger or Postman
Use Telescope for live request tracing and Swagger/Postman for public-facing docs.

🔍 When to Use Telescope vs Swagger

Feature	Telescope	Swagger/Postman
Real-time API monitoring	✅ Yes	❌ No
Generates markdown/OpenAPI	❌ No	✅ Yes
Great for debugging	✅ Yes	❌ No
Export/share documentation	❌ Not directly	✅ Yes
Requires coding	❌ Minimal	✅ Moderate

✅ Combine both: Use Telescope during development, and use tools like Swagger/OpenAPI for final documentation.

🔄 Alternative Tools to Auto-Generate API Docs

If you’re looking to generate complete API docs automatically, consider pairing Telescope with:

Laravel Scribe
Generate API documentation from routes and controller annotations.
Swagger (OpenAPI) + Laravel Annotations
Use libraries like DarkaOnLine/L5-Swagger.
Postman
Use Postman to manually test and export collections with examples.

✅ Conclusion

Laravel Telescope may not be a traditional API documentation tool, but it’s an incredibly powerful companion for developers looking to understand, debug, and document their Laravel APIs quickly. It gives you real-time insights into how your endpoints are being hit, what payloads they receive, and how they respond — which is essential when maintaining APIs.

If you’re working on a Laravel-based API and want to speed up the documentation process, start with Telescope. Then export your findings into formal tools like Swagger, Postman, or Markdown-based documentation.

Telescope helps you discover your API — even before you’ve written a single line of documentation.

Would you like help integrating Laravel Scribe or Swagger alongside Telescope for a complete API documentation suite? Just let me know!

Post Views: 3