Generating and exporting API specification with Scramble

December 19, 2024

On this page

Using the exported spec for rendering the docs UI CI integration and version control of the API specification

Scramble PRO

Comprehensive API documentation generation for Spatie’s Laravel Data and Laravel Query Builder.

Generate and export an API specification using CLI with Scramble.

From the very beginning of Scramble, it was focused on generating API documentation on the fly: the specification is generated when you hit the /docs/api endpoint. This keeps API documentation up-to-date and always relevant.

Scramble also has the ability to export the OpenAPI 3.1.0 specification from the CLI by running the scramble:exportcommand:

php artisan scramble:export

This command generates the api.json file in the project’s root.

You can read more in the documentation: https://scramble.dedoc.co/usage/export.

Here are a few ideas this unlocks.

Using the exported spec for rendering the docs UI

When you hit the /docs/api endpoint, Scramble generates the documentation from scratch. If you want to make your documentation public, you might prefer to reuse the generated specification and avoid generating it every time.

To do this, define the route for the documentation UI manually:

use Dedoc\Scramble\Scramble;
use Dedoc\Scramble\Http\Middleware\RestrictedDocsAccess;

Route::get('/documentation-api', function () {
    return view('scramble::docs', [
        'spec' => file_get_contents(base_path('api.json')),
        'config' => Scramble::getGeneratorConfig('default'),
    ]);
})
->middleware(Scramble::getGeneratorConfig('default')->get('middleware', [RestrictedDocsAccess::class]));

If you want to disable the default routes Scramble creates, call Scramble::ignoreDefaultRoutes in one of your service providers:

use Dedoc\Scramble\Scramble;

public function register(): void
{
    Scramble::ignoreDefaultRoutes();
}

CI integration and version control of the API specification

When you generate the api.json file, you can add it to Git and commit it whenever the API changes. To avoid running the export command manually, set up your CI process to do this automatically. Here is an example config for GitHub Actions.

To simplify the CI setup, I used https://kirschbaumdevelopment.com/insights/laravel-github-actions as a reference.

First, here is the basic config for the CI to prepare the app for running the export command. In my case, this is the Scramble Demo app:

on: push
name: CI
jobs:
  phpunit:
    runs-on: ubuntu-latest
    container:
      image: kirschbaumdevelopment/laravel-test-runner:8.2

    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 1
          ref: ${{ github.ref_name }}

      - name: Install composer dependencies
        run: |
          composer install --no-scripts

      - name: Prepare Laravel Application
        run: |
          cp .env.example .env
          php artisan key:generate
          php artisan migrate

      - name: Run Testsuite
        run: vendor/bin/phpunit tests/

The idea is to run the export command when the application is ready and then commit the file. Here are the changes to do just that:

on: push
name: CI
permissions:
  contents: write
jobs:
  phpunit:
    runs-on: ubuntu-latest
    container:
      image: kirschbaumdevelopment/laravel-test-runner:8.2

    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 1
          ref: ${{ github.ref_name }}

      - name: Install composer dependencies
        run: |
          composer install --no-scripts

      - name: Prepare Laravel Application
        run: |
          cp .env.example .env
          php artisan key:generate
          php artisan migrate

      - name: Run Testsuite
        run: vendor/bin/phpunit tests/

      - name: Generate and commit API specification
        run:  |
          php artisan scramble:export
          git config --global --add safe.directory '*'
          git config --global user.name 'GitHub Actions'
          git config --global user.email 'githubactions@users.noreply.github.com'
          git add api.json
          git commit -m "API spec update"
          git push

If the API changes, you will see the commit in your history, allowing you to view the changes made to the API.

For example, the commit that introduced the change, and here is the automatic CI commit documenting that change.

},
"user_id": {
    "type": "integer",
    "description": "The ID of the user who made the booking."
    "description": "The user who made the booking."
},
"date": {
    "type": "string",

You can see the demo here: https://github.com/dedoc/demo-scramble.

scramble:export is a handy command that allows you to export the specification. You can later render docs using it, push it to version control, or feed it into an API client generator.

Have fun!