Getting started
Now, after you have Scramble installed, first thing to do is to ensure that all the API routes are added to the docs.
Routes resolution
By default, all routes starting with api
are added to the documentation. For example, yoursite.com/api/users
will be added to the docs. This can be customized by modifying scramble.api_path
config value. For example, if you want to add all routes starting with api/v1
, you should set scramble.api_path
to api/v1
. Make sure you publish the config file first.
If your API routes use a different domain, you can account for it by modifying scramble.api_domain
config value. By default, it is set to null
which means that the current domain will be used. So if your API routes are on api.yoursite.com
, you should set scramble.api_domain
to api.yoursite.com
.
Also, you may provide your own route resolver function using Scramble::route
in the boot
method of a service provider. This way you can exclude routes or include just few ones. It will take precedence over the default route matching. For example, in your AppServiceProvider
:
Route resolver function accepts a route and return bool
determining if the route should be added to docs or not.
At this point your docs should be available at /docs/api
URI.
Docs authorization
By default, you will only be able to access /docs/api
route in the local
environment.
Define viewApiDocs
gate if you need to allow access in other environments.
To illustrate, if you want only the user with the email admin@app.com
to access the docs in the production
environment, you need to register the gate in one of your app’s service providers, such as App\Providers\AppServiceProvider
:
API overview page
When you visit /docs/api
first time, the page itself is almost empty.
You can add some content there by publishing the config file and setting scramble.info.description
config value. Content can be as long as you want. Markdown is supported.
Customizing API documentation’s URL
When installed, Scramble registers 2 routes by default:
/docs/api
– The website for API documentation/docs/api.json
– The OpenAPI document in JSON format that describes the API
This can be customized by ignoring default routes using Scramble::ignoreDefaultRoutes
, and then registering custom routes manually using the Scramble::registerUiRoute
and Scramble::registerJsonSpecificationRoute
methods.
You may call Scramble::ignoreDefaultRoutes
from the register
method of your application’s App\Providers\AppServiceProvider
.
And route registering methods can be called in routes/web.php
. You can combine this with Laravel’s route registering features to get the routes you need. For example, here’s how you can register an API documentation website available on a subdomain:
Now the API documentation website will be available on docs.example.com/api
and OpenAPI JSON document on docs.example.com/api.json
.