Registering an API | laravel-openapi-cli | Spatie

 SPATIE

  Laravel OpenAPI CLI
======================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-openapi-cli](https://spatie.be/docs/laravel-openapi-cli/v1)  Basic-usage  Registering an API

 Version   v1

 Other versions for crawler [v1](https://spatie.be/docs/laravel-openapi-cli/v1)

- [ Introduction ](https://spatie.be/docs/laravel-openapi-cli/v1/introduction)
- [ Support us ](https://spatie.be/docs/laravel-openapi-cli/v1/support-us)
- [ Installation & setup ](https://spatie.be/docs/laravel-openapi-cli/v1/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-openapi-cli/v1/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-openapi-cli/v1/changelog)
- [ About us ](https://spatie.be/docs/laravel-openapi-cli/v1/about-us)

Basic usage
-----------

- [ Registering an API ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/registering-an-api)
- [ Command naming ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/command-naming)
- [ Path & query parameters ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/path-and-query-parameters)
- [ Sending data ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/sending-data)
- [ Listing endpoints ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/listing-endpoints)
- [ Authentication ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/authentication)
- [ Output formatting ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/output-formatting)

Advanced usage
--------------

- [ Error handling ](https://spatie.be/docs/laravel-openapi-cli/v1/advanced-usage/error-handling)
- [ Multiple APIs ](https://spatie.be/docs/laravel-openapi-cli/v1/advanced-usage/multiple-apis)
- [ Debugging ](https://spatie.be/docs/laravel-openapi-cli/v1/advanced-usage/debugging)
- [ Command reference ](https://spatie.be/docs/laravel-openapi-cli/v1/advanced-usage/command-reference)

 Registering an API
==================

###  On this page

1. [ Direct registration (no namespace) ](#content-direct-registration-no-namespace)
2. [ Remote specs ](#content-remote-specs)

Register your OpenAPI spec in a service provider (typically `AppServiceProvider`). You can use a local file path or a remote URL:

```
use Spatie\OpenApiCli\Facades\OpenApiCli;

public function boot()
{
    OpenApiCli::register(base_path('openapi/bookstore-api.yaml'), 'bookstore')
        ->baseUrl('https://api.example-bookstore.com')
        ->bearer(env('BOOKSTORE_TOKEN'));
}
```

The second argument is the **namespace** - it groups all commands under a common prefix. For a spec with `GET /books`, `POST /books`, and `GET /books/{book_id}/reviews`, you get:

- `bookstore:get-books`
- `bookstore:post-books`
- `bookstore:get-books-reviews`
- `bookstore:list`

Direct registration (no namespace)
----------------------------------------------------------------------------------------------------------------------------------------------------------

If you omit the namespace, commands are registered directly without a prefix. This is useful for **Laravel Zero** CLI tools or any app where a single API is the primary interface:

```
OpenApiCli::register(base_path('openapi/api.yaml'))
    ->baseUrl('https://api.example.com')
    ->bearer(env('API_TOKEN'));
```

For the same spec, you get:

- `get-books`
- `post-books`
- `get-books-reviews`

Note: The `list` command is **not registered** when no namespace is set, since it would conflict with Laravel's built-in `list` command.

Remote specs
--------------------------------------------------------------------------------------------

You can register a spec directly from a URL. The spec is fetched via HTTP on every boot by default:

```
OpenApiCli::register('https://api.example.com/openapi.yaml', 'example')
    ->baseUrl('https://api.example.com')
    ->bearer(env('EXAMPLE_TOKEN'));
```

To enable caching (recommended for production), call `cache()`:

```
OpenApiCli::register('https://api.example.com/openapi.yaml', 'example')
    ->cache(); // cache for 60 seconds (default)
```

You can customize the TTL, cache store, and key prefix:

```
OpenApiCli::register('https://api.example.com/openapi.yaml', 'example')
    ->cache(ttl: 600); // 10 minutes

OpenApiCli::register('https://api.example.com/openapi.yaml', 'example')
    ->cache(ttl: 600, store: 'redis', prefix: 'my-api:');
```