@lukoweb/apitogo 0.1.105 → 0.1.106
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -23
- package/dist/cli/cli.js +5 -5
- package/docs/cli/commands.md +33 -34
- package/docs/cli/overview.md +24 -23
- package/docs/cli/setup.md +27 -46
- package/docs/cli/shape.md +33 -29
- package/docs/configuration/authentication.md +1 -1
- package/docs/configuration/footer.mdx +7 -7
- package/docs/configuration/make-config.mdx +33 -33
- package/docs/mcp/shape.md +4 -4
- package/docs/quickstart.md +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
<img src="./assets/3.png" width=630 alt="APIToGo Docs & Developer Portal">
|
|
5
5
|
</a>
|
|
6
6
|
|
|
7
|
-
[](./LICENSE.md)
|
|
8
|
+
[](https://github.com/zuplo/zudoku)
|
|
9
9
|
|
|
10
10
|
</div>
|
|
11
11
|
|
|
@@ -13,40 +13,41 @@
|
|
|
13
13
|
|
|
14
14
|
API documentation should always be free.
|
|
15
15
|
|
|
16
|
-
<a href="#-installation"><strong>Installation</strong></a> ·
|
|
16
|
+
<a href="#-installation"><strong>Installation</strong></a> ·
|
|
17
|
+
<a href="#-examples"><strong>Examples</strong></a> ·
|
|
18
|
+
<a href="#-contributing--community"><strong>Contributing</strong></a> ·
|
|
19
|
+
<a href="#-motivation"><strong>Motivation</strong></a>
|
|
17
20
|
|
|
18
21
|
---
|
|
19
22
|
|
|
20
23
|
## 📢 Attribution
|
|
21
24
|
|
|
22
|
-
This project is **based on [Zudoku](https://github.com/zuplo/zudoku)**, an open-source API
|
|
23
|
-
Modifications, branding, and extensions by **APIToGo**.
|
|
25
|
+
This project is **based on [Zudoku](https://github.com/zuplo/zudoku)**, an open-source API
|
|
26
|
+
documentation framework licensed under MIT. Modifications, branding, and extensions by **APIToGo**.
|
|
24
27
|
|
|
25
28
|
---
|
|
26
29
|
|
|
27
30
|
## Introduction
|
|
28
31
|
|
|
29
|
-
**APIToGo** is a customizable API documentation framework for building high-quality developer
|
|
32
|
+
**APIToGo** is a customizable API documentation framework for building high-quality developer
|
|
33
|
+
experiences around OpenAPI (and future GraphQL support).
|
|
30
34
|
|
|
31
35
|
Built on top of Zudoku, with enhancements and branding tailored for APIToGo.
|
|
32
36
|
|
|
33
37
|
Because great API documentation frameworks should be:
|
|
34
38
|
|
|
35
|
-
🌍 Free & Open Source
|
|
36
|
-
✅ OpenAPI powered
|
|
37
|
-
🔩 Extensible with Plugins
|
|
38
|
-
⚡ Fast and developer-friendly
|
|
39
|
+
🌍 Free & Open Source ✅ OpenAPI powered 🔩 Extensible with Plugins ⚡ Fast and developer-friendly
|
|
39
40
|
🔧 Easy to maintain
|
|
40
41
|
|
|
41
42
|
---
|
|
42
43
|
|
|
43
44
|
## ✨ Features
|
|
44
45
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
46
|
+
- 🚀 Generate documentation from single or multiple OpenAPI schemas
|
|
47
|
+
- 📄 Create MDX pages for custom documentation
|
|
48
|
+
- 🔐 Authentication via OpenID or OAuth2
|
|
49
|
+
- 🧪 Built-in API playground
|
|
50
|
+
- 🌑 Dark mode support
|
|
50
51
|
|
|
51
52
|
---
|
|
52
53
|
|
|
@@ -55,18 +56,18 @@ Because great API documentation frameworks should be:
|
|
|
55
56
|
### ⚡️ Quick start
|
|
56
57
|
|
|
57
58
|
```
|
|
58
|
-
|
|
59
|
+
npx @lukoweb/apitogo@latest init
|
|
59
60
|
```
|
|
60
61
|
|
|
61
|
-
|
|
62
|
+
_(You may later replace this with your own CLI if you build one)_
|
|
62
63
|
|
|
63
64
|
---
|
|
64
65
|
|
|
65
66
|
## 🎓 Examples
|
|
66
67
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
68
|
+
- API documentation portals
|
|
69
|
+
- Developer portals with authentication
|
|
70
|
+
- Internal API documentation systems
|
|
70
71
|
|
|
71
72
|
---
|
|
72
73
|
|
|
@@ -78,7 +79,8 @@ Contributions are welcome. Please follow standard GitHub workflows.
|
|
|
78
79
|
|
|
79
80
|
## 🎯 Motivation
|
|
80
81
|
|
|
81
|
-
APIToGo builds on the solid foundation of Zudoku to provide a customizable and scalable API
|
|
82
|
+
APIToGo builds on the solid foundation of Zudoku to provide a customizable and scalable API
|
|
83
|
+
documentation solution.
|
|
82
84
|
|
|
83
85
|
---
|
|
84
86
|
|
|
@@ -86,7 +88,7 @@ APIToGo builds on the solid foundation of Zudoku to provide a customizable and s
|
|
|
86
88
|
|
|
87
89
|
This project is licensed under the MIT License.
|
|
88
90
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
+
- Original work: Zudoku (© Zuplo)
|
|
92
|
+
- Modifications: APIToGo
|
|
91
93
|
|
|
92
94
|
See the full [LICENSE](./LICENSE.md).
|
package/dist/cli/cli.js
CHANGED
|
@@ -5801,7 +5801,7 @@ import {
|
|
|
5801
5801
|
// package.json
|
|
5802
5802
|
var package_default = {
|
|
5803
5803
|
name: "@lukoweb/apitogo",
|
|
5804
|
-
version: "0.1.
|
|
5804
|
+
version: "0.1.106",
|
|
5805
5805
|
type: "module",
|
|
5806
5806
|
sideEffects: [
|
|
5807
5807
|
"**/*.css",
|
|
@@ -21646,7 +21646,7 @@ function resolveInitOutputDirectory(dirArg, name) {
|
|
|
21646
21646
|
const fromName = name?.trim();
|
|
21647
21647
|
if (!fromName) {
|
|
21648
21648
|
throw new Error(
|
|
21649
|
-
"apitogo init
|
|
21649
|
+
"apitogo init scaffolds into a named folder (default `dev-portal`). Pass a folder name or `--name` when using `.`."
|
|
21650
21650
|
);
|
|
21651
21651
|
}
|
|
21652
21652
|
return {
|
|
@@ -21665,7 +21665,7 @@ async function init2(argv) {
|
|
|
21665
21665
|
const openapiSearch = argv.openapiSearch ?? "nearby";
|
|
21666
21666
|
try {
|
|
21667
21667
|
const { outputDirectory, siteName } = resolveInitOutputDirectory(
|
|
21668
|
-
argv.dir ?? "
|
|
21668
|
+
argv.dir ?? "dev-portal",
|
|
21669
21669
|
argv.name
|
|
21670
21670
|
);
|
|
21671
21671
|
const docToolPath = resolveDocToolPath();
|
|
@@ -21767,8 +21767,8 @@ var init_default = {
|
|
|
21767
21767
|
command: "init [dir]",
|
|
21768
21768
|
builder: (yargs2) => yargs2.positional("dir", {
|
|
21769
21769
|
type: "string",
|
|
21770
|
-
describe: "
|
|
21771
|
-
default: "
|
|
21770
|
+
describe: "Directory to scaffold into (default `dev-portal`)",
|
|
21771
|
+
default: "dev-portal",
|
|
21772
21772
|
normalize: true
|
|
21773
21773
|
}).option("name", {
|
|
21774
21774
|
type: "string",
|
package/docs/cli/commands.md
CHANGED
|
@@ -10,54 +10,53 @@ same commands so agents and humans get identical behavior.
|
|
|
10
10
|
|
|
11
11
|
## Lifecycle (prefer these)
|
|
12
12
|
|
|
13
|
-
| Command | Role
|
|
14
|
-
| ------------------------ |
|
|
15
|
-
| `init` | Scaffold portal (
|
|
16
|
-
| `config` / `make-config` | Write or update `apitogo.config.json` (interactive or flags)
|
|
17
|
-
| `run` / `dev` | Local preview server
|
|
18
|
-
| `build` | Production build (`--preview` to serve locally)
|
|
19
|
-
| `check` | Publish readiness (secrets, manifest, site validation)
|
|
20
|
-
| `project create` | Create a platform project (plan unselected)
|
|
21
|
-
| `deploy` / `apply` | Publish config to platform (apihub + portal)
|
|
22
|
-
| `status` | Account, project, and live readiness
|
|
23
|
-
| `teardown --yes` | Delete the linked platform project
|
|
13
|
+
| Command | Role |
|
|
14
|
+
| ------------------------ | --------------------------------------------------------------------- |
|
|
15
|
+
| `init` | Scaffold portal (default `./dev-portal`; OpenAPI discovery + secrets) |
|
|
16
|
+
| `config` / `make-config` | Write or update `apitogo.config.json` (interactive or flags) |
|
|
17
|
+
| `run` / `dev` | Local preview server |
|
|
18
|
+
| `build` | Production build (`--preview` to serve locally) |
|
|
19
|
+
| `check` | Publish readiness (secrets, manifest, site validation) |
|
|
20
|
+
| `project create` | Create a platform project (plan unselected) |
|
|
21
|
+
| `deploy` / `apply` | Publish config to platform (apihub + portal) |
|
|
22
|
+
| `status` | Account, project, and live readiness |
|
|
23
|
+
| `teardown --yes` | Delete the linked platform project |
|
|
24
24
|
|
|
25
25
|
## Scaffold and config
|
|
26
26
|
|
|
27
|
-
| Command | Role
|
|
28
|
-
| ------------ |
|
|
29
|
-
| `init [dir]` |
|
|
30
|
-
| `config` | Interactive on TTY; flags: `--openapi`, `--page-*`, `--plan`, `--backend`, `--theme`, `--patch`, `--json`
|
|
27
|
+
| Command | Role |
|
|
28
|
+
| ------------ | ----------------------------------------------------------------------------------------------------------- |
|
|
29
|
+
| `init [dir]` | Folder (default `dev-portal`); `--name`, `--install` (default), `--overwrite`, `--json`, `--openapi-search` |
|
|
30
|
+
| `config` | Interactive on TTY; flags: `--openapi`, `--page-*`, `--plan`, `--backend`, `--theme`, `--patch`, `--json` |
|
|
31
31
|
|
|
32
|
-
`npx @lukoweb/
|
|
33
|
-
|
|
34
|
-
to skip those prompts. See [Install the CLI](./setup.md#scaffold-options).
|
|
32
|
+
`npx @lukoweb/apitogo@latest init` auto-wires nearby OpenAPI and `docs/`/`doc/` markdown after
|
|
33
|
+
scaffold. See [Install the CLI](./setup.md#scaffold-options).
|
|
35
34
|
|
|
36
35
|
See [Make config (CLI)](../configuration/make-config.mdx) for all `config` flags.
|
|
37
36
|
|
|
38
37
|
## Local development
|
|
39
38
|
|
|
40
|
-
| Command | Role
|
|
41
|
-
| ----------------- |
|
|
39
|
+
| Command | Role |
|
|
40
|
+
| ----------------- | --------------------------------------------------------- |
|
|
42
41
|
| `run` | Run the local portal server (`--port`, `--open`, `--ssr`) |
|
|
43
|
-
| `dev` | Alias for `run`
|
|
44
|
-
| `build` | Production static build
|
|
45
|
-
| `build --preview` | Build then serve locally
|
|
42
|
+
| `dev` | Alias for `run` |
|
|
43
|
+
| `build` | Production static build |
|
|
44
|
+
| `build --preview` | Build then serve locally |
|
|
46
45
|
|
|
47
46
|
## Platform (requires API credentials)
|
|
48
47
|
|
|
49
|
-
| Command
|
|
50
|
-
|
|
|
51
|
-
| `project create --name`
|
|
52
|
-
| `check`
|
|
48
|
+
| Command | Role |
|
|
49
|
+
| -------------------------- | -------------------------------------------------------------- |
|
|
50
|
+
| `project create --name` | Create platform project only |
|
|
51
|
+
| `check` | Dry-run publish readiness |
|
|
53
52
|
| `deploy` | Full publish — project, plans, apihub, portal backend/frontend |
|
|
54
53
|
| `deploy --only <resource>` | Limit to `apihub`, `portal-backend`, or `portal-frontend` |
|
|
55
54
|
| `deploy --force` | Redeploy selected resources even when healthy |
|
|
56
55
|
| `deploy --platform-plan` | Select Free / Starter / Professional hosting |
|
|
57
56
|
| `deploy --resume-from` | Resume interrupted publish |
|
|
58
57
|
| `apply` | Alias for `deploy` |
|
|
59
|
-
| `status`
|
|
60
|
-
| `teardown --yes`
|
|
58
|
+
| `status` | Whoami + project + live verification |
|
|
59
|
+
| `teardown --yes` | Delete platform project (confirmation required) |
|
|
61
60
|
|
|
62
61
|
Env: `APITOGO_API_KEY_ID`, `APITOGO_API_SECRET`. Optional: `APITOGO_API_URL`.
|
|
63
62
|
|
|
@@ -74,11 +73,11 @@ There is no CLI command for arbitrary home page content.
|
|
|
74
73
|
|
|
75
74
|
These print a redirect message — use the replacement:
|
|
76
75
|
|
|
77
|
-
| Removed | Use instead
|
|
78
|
-
| --------------------------- |
|
|
79
|
-
| `preview` | `npx apitogo build --preview` or `npx apitogo run`
|
|
80
|
-
| `remove` | `npx apitogo teardown --yes`
|
|
81
|
-
| `configure-github-workflow` | `npx apitogo deploy`
|
|
76
|
+
| Removed | Use instead |
|
|
77
|
+
| --------------------------- | -------------------------------------------------- |
|
|
78
|
+
| `preview` | `npx apitogo build --preview` or `npx apitogo run` |
|
|
79
|
+
| `remove` | `npx apitogo teardown --yes` |
|
|
80
|
+
| `configure-github-workflow` | `npx apitogo deploy` |
|
|
82
81
|
|
|
83
82
|
## Related
|
|
84
83
|
|
package/docs/cli/overview.md
CHANGED
|
@@ -6,14 +6,15 @@ sidebar_icon: terminal
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
The **`apitogo`** CLI lets you manage developer portals from the terminal. You scaffold and shape
|
|
9
|
-
local files, preview with `npx apitogo run`, and publish to APItoGo hosting with
|
|
9
|
+
local files, preview with `npx apitogo run`, and publish to APItoGo hosting with
|
|
10
|
+
`npx apitogo deploy`.
|
|
10
11
|
|
|
11
12
|
**First time?** Install and wire credentials → **[Install the CLI](./setup.md)**. Then follow
|
|
12
13
|
[Shape](./shape.md) and [Go live](./go-live.md).
|
|
13
14
|
|
|
14
15
|
## What you get
|
|
15
16
|
|
|
16
|
-
- Scaffold a local portal site (`npx @lukoweb/
|
|
17
|
+
- Scaffold a local portal site (`npx @lukoweb/apitogo@latest init`)
|
|
17
18
|
- Shape backend, OpenAPI, plans, and docs pages via `npx apitogo config` and file edits
|
|
18
19
|
- Preview locally (`npx apitogo run`)
|
|
19
20
|
- Publish to APItoGo hosting (`npx apitogo deploy`) with platform plans **Free**, **Starter**, or
|
|
@@ -24,10 +25,10 @@ local files, preview with `npx apitogo run`, and publish to APItoGo hosting with
|
|
|
24
25
|
|
|
25
26
|
### Shell environment (for apply / status / teardown)
|
|
26
27
|
|
|
27
|
-
| Variable
|
|
28
|
-
|
|
|
29
|
-
| `APITOGO_API_KEY_ID`
|
|
30
|
-
| `APITOGO_API_SECRET`
|
|
28
|
+
| Variable | Required | Purpose |
|
|
29
|
+
| -------------------- | -------- | ----------------- |
|
|
30
|
+
| `APITOGO_API_KEY_ID` | Yes | Platform API auth |
|
|
31
|
+
| `APITOGO_API_SECRET` | Yes | Platform API auth |
|
|
31
32
|
|
|
32
33
|
### Local machine
|
|
33
34
|
|
|
@@ -38,21 +39,21 @@ local files, preview with `npx apitogo run`, and publish to APItoGo hosting with
|
|
|
38
39
|
|
|
39
40
|
## Changing your site
|
|
40
41
|
|
|
41
|
-
| Approach
|
|
42
|
-
|
|
|
42
|
+
| Approach | When it helps |
|
|
43
|
+
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
43
44
|
| **`npx apitogo config`** | Wire OpenAPI, custom pages, gateway plans, and site title from the terminal. See [Make config](../configuration/make-config.mdx). |
|
|
44
|
-
| **Edit files directly**
|
|
45
|
+
| **Edit files directly** | Full control — `apitogo.config.json`, `pages/**`, `landing/LandingPage.tsx`, etc. |
|
|
45
46
|
|
|
46
47
|
Common CLI shape tasks:
|
|
47
48
|
|
|
48
|
-
| Change
|
|
49
|
-
|
|
|
50
|
-
| Backend runtime
|
|
51
|
-
| OpenAPI + API Reference nav
|
|
52
|
-
| Custom docs pages
|
|
53
|
-
| Gateway / API plans
|
|
54
|
-
| Site title
|
|
55
|
-
| Theme, fonts, branding, projectId
|
|
49
|
+
| Change | How |
|
|
50
|
+
| --------------------------------- | ------------------------------------------------- |
|
|
51
|
+
| Backend runtime | `npx apitogo config` (backend) |
|
|
52
|
+
| OpenAPI + API Reference nav | `npx apitogo config` (openapi) |
|
|
53
|
+
| Custom docs pages | `npx apitogo config` (page) or add under `pages/` |
|
|
54
|
+
| Gateway / API plans | `npx apitogo config` (plan) or edit manifest |
|
|
55
|
+
| Site title | `--title` or edit `apitogo.config.json` |
|
|
56
|
+
| Theme, fonts, branding, projectId | Edit `apitogo.config.json` |
|
|
56
57
|
|
|
57
58
|
Home page content often lives in `landing/LandingPage.tsx`. Site footer can live under
|
|
58
59
|
`modules.landing.content.footer` in `apitogo.config.json`.
|
|
@@ -71,12 +72,12 @@ Details: [Manifest](../configuration/manifest.md).
|
|
|
71
72
|
Both paths use the same config-first model. `npx apitogo deploy` runs the same engine as MCP
|
|
72
73
|
`publish_dev_portal`.
|
|
73
74
|
|
|
74
|
-
| Task | CLI
|
|
75
|
-
| ----------------- |
|
|
76
|
-
| Scaffold | `
|
|
77
|
-
| Shape config | `npx apitogo config` + file edits
|
|
78
|
-
| Preview | `npx apitogo run`
|
|
79
|
-
| Publish | `npx apitogo deploy`
|
|
75
|
+
| Task | CLI | MCP (agent) |
|
|
76
|
+
| ----------------- | --------------------------------------------- | --------------------------------------------- |
|
|
77
|
+
| Scaffold | `npx @lukoweb/apitogo@latest init` | `create_dev_portal` |
|
|
78
|
+
| Shape config | `npx apitogo config` + file edits | `apply_product_intent` (shape) |
|
|
79
|
+
| Preview | `npx apitogo run` | `npm run dev` / preview tool |
|
|
80
|
+
| Publish | `npx apitogo deploy` | `publish_dev_portal` |
|
|
80
81
|
| Status / teardown | `npx apitogo status` / `npx apitogo teardown` | `verify_dev_portal_live` / `teardown_project` |
|
|
81
82
|
|
|
82
83
|
Prefer MCP when an agent should drive changes. Prefer CLI for CI, scripts, or terminal-only
|
package/docs/cli/setup.md
CHANGED
|
@@ -6,8 +6,8 @@ sidebar_icon: terminal
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
Use the **`apitogo`** CLI (`@lukoweb/apitogo`) to scaffold a local portal, shape
|
|
9
|
-
`apitogo.config.json`, preview with `npx apitogo run`, and publish with `npx apitogo deploy`.
|
|
10
|
-
commands (`deploy`, `status`, `teardown`) use the same engine as MCP `publish_dev_portal`.
|
|
9
|
+
`apitogo.config.json`, preview with `npx apitogo run`, and publish with `npx apitogo deploy`.
|
|
10
|
+
Platform commands (`deploy`, `status`, `teardown`) use the same engine as MCP `publish_dev_portal`.
|
|
11
11
|
|
|
12
12
|
Examples in these docs use **`npx apitogo`** so they run the project-local CLI. A global install is
|
|
13
13
|
optional and not required.
|
|
@@ -15,8 +15,8 @@ optional and not required.
|
|
|
15
15
|
## Prerequisites
|
|
16
16
|
|
|
17
17
|
- **Node.js 20+**
|
|
18
|
-
- Platform API credentials from [apitogo.com](https://apitogo.com) when you run `npx apitogo deploy`
|
|
19
|
-
key id + secret)
|
|
18
|
+
- Platform API credentials from [apitogo.com](https://apitogo.com) when you run `npx apitogo deploy`
|
|
19
|
+
(API key id + secret)
|
|
20
20
|
|
|
21
21
|
## Install
|
|
22
22
|
|
|
@@ -26,65 +26,46 @@ commands add it to your project and `npm install` puts it on `node_modules/.bin`
|
|
|
26
26
|
|
|
27
27
|
### New project (recommended)
|
|
28
28
|
|
|
29
|
-
`npx @lukoweb/
|
|
29
|
+
`npx @lukoweb/apitogo@latest init` scaffolds into `./dev-portal` by default (pass a folder name to
|
|
30
|
+
override). It installs dependencies, writes `apitogo.config.json` and secrets artifacts, and
|
|
30
31
|
auto-wires nearby OpenAPI (`openapi.yaml` / `swagger.yaml`) plus markdown in `docs/` / `doc/` /
|
|
31
32
|
`documents/` / `documentation/` folders:
|
|
32
33
|
|
|
33
34
|
```bash
|
|
34
|
-
npx @lukoweb/
|
|
35
|
+
npx @lukoweb/apitogo@latest init
|
|
35
36
|
cd dev-portal
|
|
36
|
-
npx apitogo
|
|
37
|
-
npm run dev
|
|
37
|
+
npx apitogo run
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
|
|
41
|
-
`bunx @lukoweb/create-apitogo`.
|
|
42
|
-
|
|
43
|
-
Non-interactive:
|
|
40
|
+
Named folder or site name:
|
|
44
41
|
|
|
45
42
|
```bash
|
|
46
|
-
npx @lukoweb/
|
|
47
|
-
cd
|
|
48
|
-
npx apitogo
|
|
43
|
+
npx @lukoweb/apitogo@latest init ./my-portal --name "Books API"
|
|
44
|
+
cd ./my-portal
|
|
45
|
+
npx apitogo run
|
|
49
46
|
```
|
|
50
47
|
|
|
51
48
|
#### Scaffold options
|
|
52
49
|
|
|
53
|
-
| Flag
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
| `--
|
|
57
|
-
| `--
|
|
58
|
-
| `--
|
|
59
|
-
| `--
|
|
60
|
-
|
|
61
|
-
Omit flags to be prompted for TypeScript and ESLint. Example files are never prompted.
|
|
62
|
-
|
|
63
|
-
See `@lukoweb/create-apitogo --help` for package manager and install flags.
|
|
64
|
-
|
|
65
|
-
### Scaffold into an existing folder
|
|
66
|
-
|
|
67
|
-
`npx @lukoweb/apitogo init` writes `package.json` with `@lukoweb/apitogo` as a dependency. Run **`npm install`**
|
|
68
|
-
before other `npx apitogo` commands:
|
|
69
|
-
|
|
70
|
-
```bash
|
|
71
|
-
npx @lukoweb/apitogo init ./dev-portal
|
|
72
|
-
cd ./dev-portal
|
|
73
|
-
npm install
|
|
74
|
-
npx apitogo config
|
|
75
|
-
npm run dev
|
|
76
|
-
```
|
|
50
|
+
| Flag | Effect |
|
|
51
|
+
| ------------------------- | ------------------------------------------------------------ |
|
|
52
|
+
| `[dir]` | Target folder (default `dev-portal`) |
|
|
53
|
+
| `--name <string>` | Site / package name (also used when `dir` is `.`) |
|
|
54
|
+
| `--no-install` | Skip `npm install` after scaffold |
|
|
55
|
+
| `--overwrite` | Replace an existing non-empty target directory |
|
|
56
|
+
| `--json` | Print a JSON result payload on stdout |
|
|
57
|
+
| `--openapi-search <mode>` | Auto-discover OpenAPI: `nearby` (default), `site`, or `none` |
|
|
77
58
|
|
|
78
|
-
`npx @lukoweb/apitogo init` is local only — it does not call the platform. After `config`, run
|
|
79
|
-
preview, then `npx apitogo deploy` when ready to go live.
|
|
59
|
+
`npx @lukoweb/apitogo init` is local only — it does not call the platform. After `config`, run
|
|
60
|
+
`npx apitogo run` to preview, then `npx apitogo deploy` when ready to go live.
|
|
80
61
|
|
|
81
62
|
### How to run `apitogo`
|
|
82
63
|
|
|
83
|
-
| Situation
|
|
84
|
-
|
|
|
85
|
-
| After `
|
|
86
|
-
| One-off, no project yet
|
|
87
|
-
| After [optional global install](#optional-global-install)
|
|
64
|
+
| Situation | Command |
|
|
65
|
+
| --------------------------------------------------------- | --------------------------------------------------- |
|
|
66
|
+
| After `init` or `npm install` in the project | `npx apitogo <command>` (e.g. `npx apitogo config`) |
|
|
67
|
+
| One-off, no project yet | `npx @lukoweb/apitogo <command>` |
|
|
68
|
+
| After [optional global install](#optional-global-install) | `apitogo <command>` anywhere |
|
|
88
69
|
|
|
89
70
|
`npm run dev` / `npm run build` use the project-local CLI via `package.json` scripts — no global
|
|
90
71
|
install required.
|
package/docs/cli/shape.md
CHANGED
|
@@ -5,49 +5,52 @@ description:
|
|
|
5
5
|
sidebar_icon: pencil-ruler
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
**Shape** means: create or update a local portal site (OpenAPI, plans, docs pages, auth)
|
|
9
|
-
|
|
8
|
+
**Shape** means: create or update a local portal site (OpenAPI, plans, docs pages, auth) without
|
|
9
|
+
publishing. You preview with `npx apitogo run`.
|
|
10
10
|
|
|
11
11
|
Requires the **`apitogo`** CLI (`@lukoweb/apitogo`). If you have not installed it yet, see
|
|
12
12
|
[Install the CLI](./setup.md).
|
|
13
13
|
|
|
14
14
|
## Happy path
|
|
15
15
|
|
|
16
|
-
`npx @lukoweb/
|
|
16
|
+
`npx @lukoweb/apitogo@latest init` scaffolds into `./dev-portal` by default (pass a folder name or
|
|
17
|
+
`--name` to override), installs dependencies, and wires nearby OpenAPI / docs. Then run config via
|
|
18
|
+
`npx`:
|
|
17
19
|
|
|
18
20
|
```bash
|
|
19
|
-
npx @lukoweb/
|
|
21
|
+
npx @lukoweb/apitogo@latest init
|
|
20
22
|
cd dev-portal
|
|
21
23
|
npx apitogo config # backend, OpenAPI, pages, plans (apply each immediately)
|
|
22
|
-
|
|
24
|
+
npx apitogo run # http://localhost:3000
|
|
23
25
|
```
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
Named folder:
|
|
26
28
|
|
|
27
29
|
```bash
|
|
28
|
-
npx @lukoweb/apitogo init ./
|
|
29
|
-
cd ./
|
|
30
|
-
npm install
|
|
30
|
+
npx @lukoweb/apitogo@latest init ./my-portal --name "Books API"
|
|
31
|
+
cd ./my-portal
|
|
31
32
|
npx apitogo config
|
|
32
|
-
|
|
33
|
+
npx apitogo run
|
|
33
34
|
```
|
|
34
35
|
|
|
35
|
-
`npx @lukoweb/apitogo init` does **not** call the platform. Run `npx apitogo deploy` when you are
|
|
36
|
+
`npx @lukoweb/apitogo init` does **not** call the platform. Run `npx apitogo deploy` when you are
|
|
37
|
+
ready to go live.
|
|
36
38
|
|
|
37
39
|
## Interactive config (`npx apitogo config`)
|
|
38
40
|
|
|
39
41
|
On a TTY, bare `npx apitogo config` opens the wizard. Each choice is written immediately; the loop
|
|
40
42
|
continues until you type `done`:
|
|
41
43
|
|
|
42
|
-
| Choice
|
|
43
|
-
|
|
|
44
|
+
| Choice | What it does |
|
|
45
|
+
| --------- | ----------------------------------------------------------------------- |
|
|
44
46
|
| `backend` | Set `backend.sourceDirectory`, `runtime`, and platform `runtimeVersion` |
|
|
45
|
-
| `openapi` | Link an OpenAPI file by **relative path** in `apitogo.config.json`
|
|
46
|
-
| `page`
|
|
47
|
-
| `plan`
|
|
47
|
+
| `openapi` | Link an OpenAPI file by **relative path** in `apitogo.config.json` |
|
|
48
|
+
| `page` | Create `pages/<slug>.tsx` and wire it in navigation |
|
|
49
|
+
| `plan` | Add a gateway plan (title, price, rate limit, monthly quota) |
|
|
48
50
|
|
|
49
|
-
Authentication is **on by default** — the wizard does not ask for an auth API URL.
|
|
50
|
-
fills `VITE_APITOGO_AUTHENTICATION_API_BASE_URL` after the portal backend
|
|
51
|
+
Authentication is **on by default** — the wizard does not ask for an auth API URL.
|
|
52
|
+
`npx apitogo deploy` fills `VITE_APITOGO_AUTHENTICATION_API_BASE_URL` after the portal backend
|
|
53
|
+
exists.
|
|
51
54
|
|
|
52
55
|
Fonts and colors are **not** prompted — edit `apitogo.config.json` or see
|
|
53
56
|
[Colors & theme](../customization/colors-theme.mdx).
|
|
@@ -55,7 +58,8 @@ Fonts and colors are **not** prompted — edit `apitogo.config.json` or see
|
|
|
55
58
|
**Paid plans:** if any plan has `priceAmount > 0`, you need **Starter** or **Professional** platform
|
|
56
59
|
hosting on apply. **Free** cannot publish paid gateway plans or custom domains.
|
|
57
60
|
|
|
58
|
-
Full reference: [Make config (CLI)](../configuration/make-config.mdx) ·
|
|
61
|
+
Full reference: [Make config (CLI)](../configuration/make-config.mdx) ·
|
|
62
|
+
[Gateway plans](../configuration/plans.md)
|
|
59
63
|
|
|
60
64
|
## Configure with flags
|
|
61
65
|
|
|
@@ -71,13 +75,13 @@ npx apitogo config --no-interactive
|
|
|
71
75
|
|
|
72
76
|
Common flags:
|
|
73
77
|
|
|
74
|
-
| Flag
|
|
75
|
-
|
|
|
76
|
-
| `--interactive` / `-i`
|
|
77
|
-
| `--title`
|
|
78
|
-
| `--theme`, `--site`, `--authentication` | Deep-merge JSON into config
|
|
79
|
-
| `--pages-dir`
|
|
80
|
-
| `--force`
|
|
78
|
+
| Flag | Purpose |
|
|
79
|
+
| --------------------------------------- | ---------------------------------------------------------- |
|
|
80
|
+
| `--interactive` / `-i` | Force wizard (default on TTY). `--no-interactive` skips it |
|
|
81
|
+
| `--title` | Set `site.title` |
|
|
82
|
+
| `--theme`, `--site`, `--authentication` | Deep-merge JSON into config |
|
|
83
|
+
| `--pages-dir` | Folder to scan (default: `pages`) |
|
|
84
|
+
| `--force` | Rebuild Documentation nav from disk |
|
|
81
85
|
|
|
82
86
|
## Shape by editing files
|
|
83
87
|
|
|
@@ -112,10 +116,10 @@ Shape-phase edits hot-reload when the dev server is running.
|
|
|
112
116
|
If you already have `pages/` and an OpenAPI spec:
|
|
113
117
|
|
|
114
118
|
```bash
|
|
115
|
-
npx @lukoweb/apitogo init
|
|
116
|
-
|
|
119
|
+
npx @lukoweb/apitogo@latest init
|
|
120
|
+
cd dev-portal
|
|
117
121
|
npx apitogo config
|
|
118
|
-
|
|
122
|
+
npx apitogo run
|
|
119
123
|
```
|
|
120
124
|
|
|
121
125
|
## Next
|
|
@@ -35,7 +35,7 @@ You do not need to enter this URL in `npx apitogo config`. Or set `authenticatio
|
|
|
35
35
|
|
|
36
36
|
### Local demo mode
|
|
37
37
|
|
|
38
|
-
In development (`
|
|
38
|
+
In development (`npx apitogo run`), `demoMode` is on by default when the user panel is enabled. You do
|
|
39
39
|
not need a backend URL or OIDC to explore account pages. Sign in at `/login` with:
|
|
40
40
|
|
|
41
41
|
```text
|
|
@@ -2,20 +2,20 @@
|
|
|
2
2
|
sidebar_label: Footer
|
|
3
3
|
sidebar_icon: panel-bottom-dashed
|
|
4
4
|
description:
|
|
5
|
-
Configure the site footer via modules.landing.content.footer in apitogo.config.json, or
|
|
6
|
-
for advanced layouts.
|
|
5
|
+
Configure the site footer via modules.landing.content.footer in apitogo.config.json, or
|
|
6
|
+
site.footer for advanced layouts.
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# Footer Configuration
|
|
10
10
|
|
|
11
|
-
Portal sites (MCP /
|
|
12
|
-
|
|
13
|
-
|
|
11
|
+
Portal sites (MCP / `apitogo init` scaffolds) render a global footer from **`apitogo.config.json`**
|
|
12
|
+
→ `modules.landing.content.footer`. That footer appears on home, docs, API reference, pricing, and
|
|
13
|
+
auth pages, and replaces the default “Built with APIToGo” line.
|
|
14
14
|
|
|
15
15
|
## Recommended: landing content footer (JSON)
|
|
16
16
|
|
|
17
|
-
Ask for real link columns, social URLs, copyright, and optional brand/tagline before inventing
|
|
18
|
-
|
|
17
|
+
Ask for real link columns, social URLs, copyright, and optional brand/tagline before inventing copy.
|
|
18
|
+
Example:
|
|
19
19
|
|
|
20
20
|
```json title=config.json
|
|
21
21
|
{
|
|
@@ -7,42 +7,42 @@ description:
|
|
|
7
7
|
site settings.
|
|
8
8
|
---
|
|
9
9
|
|
|
10
|
-
The **`npx apitogo config`** (alias: `make-config`) command writes **`apitogo.config.json`**. It can
|
|
11
|
-
project (package.json, tsconfig, landing and user-panel stubs, thin
|
|
12
|
-
files are missing, merge **site / theme / authentication** from
|
|
13
|
-
on a TTY (apply each change immediately), scan `pages/` for
|
|
14
|
-
**API Reference** link.
|
|
10
|
+
The **`npx apitogo config`** (alias: `make-config`) command writes **`apitogo.config.json`**. It can
|
|
11
|
+
scaffold a portal project (package.json, tsconfig, landing and user-panel stubs, thin
|
|
12
|
+
`apitogo.config.tsx`) when those files are missing, merge **site / theme / authentication** from
|
|
13
|
+
flags, run an **interactive wizard** on a TTY (apply each change immediately), scan `pages/` for
|
|
14
|
+
navigation, and wire OpenAPI plus an **API Reference** link.
|
|
15
15
|
|
|
16
|
-
Landing and user panel are **always enabled** on new configs. **Authentication is enabled by
|
|
17
|
-
on new scaffolds. The command does **not** change `redirects`.
|
|
16
|
+
Landing and user panel are **always enabled** on new configs. **Authentication is enabled by
|
|
17
|
+
default** on new scaffolds. The command does **not** change `redirects`.
|
|
18
18
|
|
|
19
19
|
## Prerequisites
|
|
20
20
|
|
|
21
21
|
Install the CLI first — see [Install the CLI](../cli/setup.md). In short:
|
|
22
22
|
|
|
23
|
-
- **New site:** `npx @lukoweb/
|
|
24
|
-
- **Existing folder:** `npx @lukoweb/apitogo init .` then `npm install`
|
|
23
|
+
- **New site:** `npx @lukoweb/apitogo@latest init` (scaffolds into `./dev-portal` by default)
|
|
25
24
|
|
|
26
25
|
Run config from the project root with `npx apitogo config`.
|
|
27
26
|
|
|
28
27
|
## What it does
|
|
29
28
|
|
|
30
|
-
1. **Ensures npm scripts** — Creates **`package.json`** (dev / build / preview) and
|
|
31
|
-
when missing, including `@lukoweb/apitogo`, landing, user-panel, and billing
|
|
29
|
+
1. **Ensures npm scripts** — Creates **`package.json`** (dev / build / preview) and
|
|
30
|
+
**`tsconfig.json`** when missing, including `@lukoweb/apitogo`, landing, user-panel, and billing
|
|
31
|
+
packages.
|
|
32
32
|
2. **Creates `apitogo.config.json`** when missing, using the current portal template (`site`,
|
|
33
|
-
`theme`, `authentication` **enabled**, `modules.docs`, **landing on**, **user panel on**).
|
|
34
|
-
**`apitogo.config.tsx`** wrapper only if that file does not already exist
|
|
35
|
-
alone).
|
|
36
|
-
3. **Patches site, theme, and auth** from `--site`, `--theme`, `--authentication`, `--title`, or
|
|
37
|
-
|
|
33
|
+
`theme`, `authentication` **enabled**, `modules.docs`, **landing on**, **user panel on**).
|
|
34
|
+
Creates a thin **`apitogo.config.tsx`** wrapper only if that file does not already exist
|
|
35
|
+
(existing TSX is left alone).
|
|
36
|
+
3. **Patches site, theme, and auth** from `--site`, `--theme`, `--authentication`, `--title`, or the
|
|
37
|
+
interactive wizard.
|
|
38
38
|
4. **Merges `navigation`** from `.md` / `.mdx` / `.tsx` files under your pages directory into a
|
|
39
39
|
Documentation category when those files exist. **Missing or empty `pages/` is fine** (common for
|
|
40
40
|
portal-only sites) — existing navigation is left alone. Other nav items are kept. Use
|
|
41
41
|
**`--force`** to rebuild Documentation items from disk when pages are present (API Reference is
|
|
42
42
|
still kept when OpenAPI is wired).
|
|
43
43
|
5. **Wires OpenAPI** when a spec is found (non-interactive) or when you enter a path in the wizard:
|
|
44
|
-
`apis: [{ type: "file", input, path: "api" }]` and a top-level **API Reference** link to `/api`
|
|
45
|
-
that link is missing. Interactive mode stores a **relative file path** in `apis[0].input` (for
|
|
44
|
+
`apis: [{ type: "file", input, path: "api" }]` and a top-level **API Reference** link to `/api`
|
|
45
|
+
if that link is missing. Interactive mode stores a **relative file path** in `apis[0].input` (for
|
|
46
46
|
example `./openapi.yaml` or `../api/openapi.yaml`).
|
|
47
47
|
6. **Interactive only** — can set **backend** (`sourceDirectory`, `runtime`, `runtimeVersion`),
|
|
48
48
|
scaffold **custom pages** under `pages/`, and append **gateway plans** to
|
|
@@ -50,8 +50,8 @@ Run config from the project root with `npx apitogo config`.
|
|
|
50
50
|
|
|
51
51
|
## Interactive wizard
|
|
52
52
|
|
|
53
|
-
On a TTY, bare `npx apitogo config` opens the wizard (no `-i` required). `-i` still works as an
|
|
54
|
-
Use `--no-interactive` (or pass flags like `--title`) for CI / non-TTY.
|
|
53
|
+
On a TTY, bare `npx apitogo config` opens the wizard (no `-i` required). `-i` still works as an
|
|
54
|
+
alias. Use `--no-interactive` (or pass flags like `--title`) for CI / non-TTY.
|
|
55
55
|
|
|
56
56
|
```bash
|
|
57
57
|
npx apitogo config
|
|
@@ -66,9 +66,9 @@ npx apitogo config
|
|
|
66
66
|
immediately)
|
|
67
67
|
2. **Wrap-up** — links to [docs.apitogo.com](https://docs.apitogo.com) for further configuration
|
|
68
68
|
|
|
69
|
-
The wizard does **not** ask for fonts, colors, logo alt text, or the auth API base URL.
|
|
70
|
-
stays **enabled**; `npx apitogo deploy` writes
|
|
71
|
-
the portal backend is provisioned.
|
|
69
|
+
The wizard does **not** ask for fonts, colors, logo alt text, or the auth API base URL.
|
|
70
|
+
Authentication stays **enabled**; `npx apitogo deploy` writes
|
|
71
|
+
`VITE_APITOGO_AUTHENTICATION_API_BASE_URL` to `.env` after the portal backend is provisioned.
|
|
72
72
|
|
|
73
73
|
If you add a **paid** plan (`priceAmount > 0`), the CLI warns that **Free platform hosting cannot
|
|
74
74
|
publish paid gateway plans or custom domains** — use Starter or Professional on apply.
|
|
@@ -85,16 +85,16 @@ npx apitogo config
|
|
|
85
85
|
|
|
86
86
|
### Options
|
|
87
87
|
|
|
88
|
-
| Option | Description
|
|
89
|
-
| ------------------------- |
|
|
90
|
-
| `--pages-dir <dir>` | Folder to scan for `.md` / `.mdx` / `.tsx` (default: `pages`)
|
|
91
|
-
| `--dir <path>` | Project root (default: current directory)
|
|
92
|
-
| `--interactive` / `-i` | Force the wizard (default on TTY). Use `--no-interactive` to skip.
|
|
93
|
-
| `--title <string>` | Set `site.title` (non-interactive)
|
|
94
|
-
| `--site <json>` | Deep-merge a JSON object into `site`
|
|
95
|
-
| `--theme <json>` | Deep-merge a JSON object into `theme`
|
|
96
|
-
| `--authentication <json>` | Deep-merge a JSON object into `authentication` (secrets stay in `.env`)
|
|
97
|
-
| `--force` | Replace Documentation nav items from disk
|
|
88
|
+
| Option | Description |
|
|
89
|
+
| ------------------------- | ----------------------------------------------------------------------- |
|
|
90
|
+
| `--pages-dir <dir>` | Folder to scan for `.md` / `.mdx` / `.tsx` (default: `pages`) |
|
|
91
|
+
| `--dir <path>` | Project root (default: current directory) |
|
|
92
|
+
| `--interactive` / `-i` | Force the wizard (default on TTY). Use `--no-interactive` to skip. |
|
|
93
|
+
| `--title <string>` | Set `site.title` (non-interactive) |
|
|
94
|
+
| `--site <json>` | Deep-merge a JSON object into `site` |
|
|
95
|
+
| `--theme <json>` | Deep-merge a JSON object into `theme` |
|
|
96
|
+
| `--authentication <json>` | Deep-merge a JSON object into `authentication` (secrets stay in `.env`) |
|
|
97
|
+
| `--force` | Replace Documentation nav items from disk |
|
|
98
98
|
|
|
99
99
|
Examples:
|
|
100
100
|
|
package/docs/mcp/shape.md
CHANGED
|
@@ -6,7 +6,7 @@ sidebar_icon: pencil-ruler
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
**Shape** means: create or update a local portal site (OpenAPI, plans, auth flags, public routes)
|
|
9
|
-
without publishing. You preview with `
|
|
9
|
+
without publishing. You preview with `npx apitogo run`.
|
|
10
10
|
|
|
11
11
|
## Happy path
|
|
12
12
|
|
|
@@ -14,7 +14,7 @@ without publishing. You preview with `npm run dev`.
|
|
|
14
14
|
apply_product_intent({ mode: "shape", siteDirectory, backend?, openApi?, plans?, auth?, gatewayPolicies?, branding? })
|
|
15
15
|
→ scaffold if needed
|
|
16
16
|
→ wire OpenAPI / plans / auth / gateway.publicRoutes
|
|
17
|
-
→ you run
|
|
17
|
+
→ you run npx apitogo run
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
Example prompt:
|
|
@@ -36,10 +36,10 @@ pass plans/backend). Then run:
|
|
|
36
36
|
|
|
37
37
|
```bash
|
|
38
38
|
cd ./dev-portal-site
|
|
39
|
-
|
|
39
|
+
npx apitogo run
|
|
40
40
|
```
|
|
41
41
|
|
|
42
|
-
`create_dev_portal` does **not** start the preview server. Use `
|
|
42
|
+
`create_dev_portal` does **not** start the preview server. Use `npx apitogo run` or
|
|
43
43
|
`preview_dev_portal_site`.
|
|
44
44
|
|
|
45
45
|
Optional: `bootstrapProject: true` on create (or `bootstrap_project`) to create the platform project
|
package/docs/quickstart.md
CHANGED