Skip to content

Commit 21fbabe

Browse files
WendellAdrielWendellAdriel
committed
Render API kit docs with Scalar at /docs over Scribe spec
1 parent faef979 commit 21fbabe

5 files changed

Lines changed: 308 additions & 23 deletions

File tree

‎kits/API/Base/README.md‎

Lines changed: 28 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Our Laravel API starter kit provides a headless, API-only starting point for bui
66

77
It is configured as a **stateless API**: clients authenticate with bearer tokens issued by [Laravel Sanctum](https://laravel.com/docs/sanctum) and no session cookies or CSRF protection are used. If you need Sanctum's stateful, SPA-style cookie authentication instead, you will need to adapt the kit accordingly.
88

9-
Out of the box it ships with token-based authentication, email verification, password updates, and account deletion endpoints, plus automatically generated API documentation powered by [Scribe](https://scribe.knuckles.wtf).
9+
Out of the box it ships with token-based authentication, email verification, password updates, and account deletion endpoints, plus a modern interactive API reference powered by [Scalar](https://scalar.com) on top of an OpenAPI spec generated by [Scribe](https://scribe.knuckles.wtf).
1010

1111
## Features
1212

@@ -16,40 +16,53 @@ Out of the box it ships with token-based authentication, email verification, pas
1616
- Password update flow gated behind email verification
1717
- Email verification with signed URLs and resend endpoint
1818
- Health check endpoint at the application root
19-
- Auto-generated, interactive API documentation via Scribe
19+
- Modern, interactive API reference rendered by Scalar from a Scribe-generated OpenAPI spec
2020

2121
## Packages
2222

2323
- [`laravel/sanctum`](https://laravel.com/docs/sanctum) — API token authentication
24-
- [`knuckleswtf/scribe`](https://scribe.knuckles.wtf) — API documentation generator
24+
- [`knuckleswtf/scribe`](https://scribe.knuckles.wtf) — OpenAPI spec generator
25+
- [`scalar/laravel`](https://github.com/scalar/laravel) — Scalar UI for the API reference
2526

2627
## API Documentation
2728

28-
The starter kit uses Scribe to generate live API docs directly from the route definitions, form requests, and API resources.
29+
The kit pairs two tools to keep the docs fully driven by your code:
2930

30-
### Generate the docs
31+
- **Scribe** inspects routes, form requests, and API resources to generate the OpenAPI document.
32+
- **Scalar** renders that document as an interactive API reference at [`/docs`](http://localhost:8000/docs).
3133

32-
```bash
33-
php artisan scribe:generate
34-
```
34+
### How it works
3535

36-
This command will:
36+
- The Scalar UI is mounted at `/docs` and is the public docs URL.
37+
- Scalar reads the OpenAPI spec live from `/scribe-source.openapi`, which Scribe registers automatically.
38+
- Running `php artisan scribe:generate` writes the spec to `storage/app/private/scribe/openapi.yaml` and a Postman collection to `storage/app/private/scribe/collection.json` — both are also exposed by Scribe at `/scribe-source.openapi` and `/scribe-source.postman`.
3739

38-
- Generate an HTML documentation site served at [`/docs`](http://localhost:8000/docs)
39-
- Write an OpenAPI spec to `public/docs/openapi.yaml`
40-
- Write a Postman collection to `public/docs/collection.json`
40+
`composer setup` runs `scribe:generate` for you, so a fresh install already has up-to-date docs the first time you boot the app.
4141

4242
### Preview the docs
4343

44-
Start the development server and visit the docs in your browser:
44+
Start the development server and open the docs in your browser:
4545

4646
```bash
4747
php artisan serve
4848
```
4949

50-
Then open [http://localhost:8000/docs](http://localhost:8000/docs). The built-in "Try It Out" playground lets you call the endpoints straight from the documentation.
50+
Then visit [http://localhost:8000/docs](http://localhost:8000/docs). The "Test Request" panel lets you call the endpoints straight from the reference.
51+
52+
### Refresh the docs after code changes
53+
54+
After adding or modifying routes, regenerate the spec so Scribe picks up the changes:
55+
56+
```bash
57+
php artisan scribe:generate
58+
```
59+
60+
Scalar reads from the live Scribe route, so the UI updates as soon as the spec is regenerated.
61+
62+
### Customizing the docs
5163

52-
To customize the output, edit `config/scribe.php`.
64+
- Edit `config/scalar.php` to change the UI — theme, layout, page title, sidebar visibility, hidden HTTP clients, and so on.
65+
- Edit `config/scribe.php` to change what ends up in the spec — included routes, authentication metadata, example languages, and the intro text shown at the top of the reference.
5366

5467
## Official Documentation
5568

‎kits/API/Base/composer.json‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@
1313
"knuckleswtf/scribe": "^5.9",
1414
"laravel/framework": "^13.6",
1515
"laravel/sanctum": "^4.3",
16-
"laravel/tinker": "^3.0"
16+
"laravel/tinker": "^3.0",
17+
"scalar/laravel": "^0.2.1"
1718
},
1819
"require-dev": {
1920
"fakerphp/faker": "^1.24",
@@ -42,7 +43,8 @@
4243
"composer install",
4344
"@php -r \"file_exists('.env') || copy('.env.example', '.env');\"",
4445
"@php artisan key:generate",
45-
"@php artisan migrate --force"
46+
"@php artisan migrate --force",
47+
"@php artisan scribe:generate"
4648
],
4749
"dev": [
4850
"Composer\\Config::disableProcessTimeout",

‎kits/API/Base/config/scalar.php‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
<?php
2+
3+
return [
4+
5+
/*
6+
|--------------------------------------------------------------------------
7+
| Scalar Domain
8+
|--------------------------------------------------------------------------
9+
|
10+
| This is the subdomain where Scalar will be accessible from. If this
11+
| setting is null, Scalar will reside under the same domain as the
12+
| application. Otherwise, this value will serve as the subdomain.
13+
|
14+
*/
15+
'domain' => null,
16+
17+
/*
18+
|--------------------------------------------------------------------------
19+
| Scalar Path
20+
|--------------------------------------------------------------------------
21+
|
22+
| This is the URI path where Scalar will be accessible from. Feel free
23+
| to change this path to anything you like. Note that the URI will not
24+
| affect the paths of its internal API that aren't exposed to users.
25+
|
26+
*/
27+
'path' => '/docs',
28+
29+
/*
30+
|--------------------------------------------------------------------------
31+
| Scalar Route Middleware
32+
|--------------------------------------------------------------------------
33+
|
34+
| These middleware will get attached onto each Scalar route, giving you
35+
| the chance to add your own middleware to this list or change any of
36+
| the existing middleware. Or, you can simply stick with this list.
37+
|
38+
*/
39+
'middleware' => ['web'],
40+
41+
/*
42+
|--------------------------------------------------------------------------
43+
| Scalar OpenAPI Document URL
44+
|--------------------------------------------------------------------------
45+
|
46+
| This is the URL to the OpenAPI document that Scalar will use to generate
47+
| the API reference. By default, it points to the latest version of the
48+
| Scalar Galaxy package. You can change this to use a custom OpenAPI file.
49+
|
50+
*/
51+
'url' => '/scribe-source.openapi',
52+
53+
/*
54+
|--------------------------------------------------------------------------
55+
| Scalar CDN URL
56+
|--------------------------------------------------------------------------
57+
|
58+
| This is the URL to the CDN where Scalar's API reference assets are hosted.
59+
| By default, it points to the jsDelivr CDN for the @scalar/api-reference
60+
| package. You can change this if you want to use a different CDN.
61+
|
62+
*/
63+
'cdn' => 'https://cdn.jsdelivr.net/npm/@scalar/api-reference',
64+
65+
/*
66+
|--------------------------------------------------------------------------
67+
| Scalar Configuration
68+
|--------------------------------------------------------------------------
69+
|
70+
| The configuration options for the Scalar API reference. This array
71+
| contains all the settings that control the behavior and appearance
72+
| of the API documentation.
73+
|
74+
*/
75+
'configuration' => [
76+
/** A string to use one of the color presets */
77+
'theme' =>
78+
// 'alternate',
79+
// 'bluePlanet',
80+
// 'deepSpace',
81+
// 'default',
82+
// 'kepler',
83+
'laravel',
84+
// 'mars',
85+
// 'moon',
86+
// 'purple',
87+
// 'saturn',
88+
// 'solarized',
89+
// 'none',
90+
91+
/** The layout to use for the references */
92+
'layout' => 'modern',
93+
94+
/** URL to a request proxy for the API client */
95+
'proxyUrl' => 'https://proxy.scalar.com',
96+
97+
/** Whether to show the sidebar */
98+
'showSidebar' => true,
99+
100+
/**
101+
* Whether to show models in the sidebar, search, and content.
102+
*/
103+
'hideModels' => false,
104+
105+
/**
106+
* Whether to show the “Download OpenAPI Document” button
107+
*/
108+
'hideDownloadButton' => false,
109+
110+
/**
111+
* Whether to show the “Test Request” button
112+
*/
113+
'hideTestRequestButton' => false,
114+
115+
/**
116+
* Whether to show the sidebar search bar
117+
*/
118+
'hideSearch' => false,
119+
120+
/** Whether dark mode is on or off initially (light mode) */
121+
'darkMode' => false,
122+
123+
/** forceDarkModeState makes it always this state no matter what*/
124+
'forceDarkModeState' => 'dark',
125+
126+
/** Whether to show the dark mode toggle */
127+
'hideDarkModeToggle' => false,
128+
129+
/** Key used with CTRL/CMD to open the search modal (defaults to 'k' e.g. CMD+k) */
130+
'searchHotKey' => 'k',
131+
132+
/**
133+
* If used, passed data will be added to the HTML header
134+
*
135+
* @see https://unhead.unjs.io/usage/composables/use-seo-meta
136+
*/
137+
'metaData' => [
138+
'title' => config('app.name').' API Reference',
139+
],
140+
141+
/**
142+
* Path to a favicon image
143+
*
144+
* @example '/favicon.svg'
145+
*/
146+
'favicon' => '',
147+
148+
/**
149+
* List of httpsnippet clients to hide from the clients menu
150+
* By default hides Unirest, pass `[]` to show all clients
151+
*/
152+
'hiddenClients' => [
153+
154+
],
155+
156+
/** Determine the HTTP client that’s selected by default */
157+
'defaultHttpClient' => [
158+
'targetId' => 'shell',
159+
'clientKey' => 'curl',
160+
],
161+
162+
/** Custom CSS to be added to the page */
163+
// 'customCss' => '',
164+
165+
/** Prefill authentication */
166+
// 'authentication' => [
167+
// // TODO
168+
// ],
169+
170+
/**
171+
* The baseServerURL is used when the spec servers are relative paths and we are using SSR.
172+
* On the client we can grab the window.location.origin but on the server we need
173+
* to use this prop.
174+
*/
175+
// 'baseServerURL' => '',
176+
177+
/**
178+
* List of servers to override the openapi spec servers
179+
*/
180+
// 'servers' => [
181+
// [
182+
// 'url' => 'https://api.scalar.com',
183+
// 'description' => 'Production server',
184+
// ],
185+
// ],
186+
187+
/**
188+
* We’re using Inter and JetBrains Mono as the default fonts. If you want to use your own fonts, set this to false.
189+
*/
190+
'withDefaultFonts' => true,
191+
192+
/**
193+
* By default we only open the relevant tag based on the url, however if you want all the tags open by default then set this configuration option :)
194+
*/
195+
'defaultOpenAllTags' => false,
196+
],
197+
198+
];

‎kits/API/Base/config/scribe.php‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,7 @@
1212
'description' => '',
1313

1414
'intro_text' => <<<'INTRO'
15-
This documentation aims to provide all the information you need to work with our API.
16-
17-
<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
18-
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>
15+
This documentation describes every endpoint exposed by the API, including the request shape, response payloads, and authentication requirements.
1916
INTRO,
2017

2118
'base_url' => config('app.url'),
@@ -27,7 +24,7 @@
2724
'domains' => ['*'],
2825
],
2926
'include' => [],
30-
'exclude' => ['/', 'sanctum/*', 'storage/*'],
27+
'exclude' => ['/', 'sanctum/*', 'storage/*', 'docs', 'docs/*'],
3128
],
3229
],
3330

@@ -41,7 +38,7 @@
4138

4239
'laravel' => [
4340
'add_routes' => true,
44-
'docs_url' => '/docs',
41+
'docs_url' => '/scribe-source',
4542
'assets_directory' => null,
4643
'middleware' => [],
4744
],

0 commit comments

Comments
 (0)