@t0.labs/daxta 0.5.0 → 0.5.1
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 +139 -91
- package/assets/empty.html +4 -4
- package/assets/example.html +10 -10
- package/assets/viewer.html +9 -9
- package/dist/build/build-spec.d.ts +3 -1
- package/dist/build/build-spec.js +6 -4
- package/dist/cli/install.js +16 -13
- package/dist/cli/main.js +15 -15
- package/dist/cli/migrate.js +2 -2
- package/dist/cli/titles.js +3 -3
- package/dist/cli/tree.d.ts +1 -1
- package/dist/cli/tree.js +4 -4
- package/dist/cli/ui.js +1 -1
- package/dist/cli/uninstall.js +16 -6
- package/dist/config.d.ts +3 -3
- package/dist/config.js +4 -4
- package/dist/index.d.ts +2 -2
- package/dist/index.js +4 -1
- package/dist/jest/global-teardown.d.ts +2 -2
- package/dist/jest/global-teardown.js +3 -3
- package/dist/jest/reporter.d.ts +1 -1
- package/dist/jest/reporter.js +6 -7
- package/dist/serve/index.d.ts +2 -2
- package/dist/serve/index.js +8 -6
- package/dist/serve/middleware.d.ts +4 -4
- package/dist/serve/middleware.js +6 -6
- package/dist/serve/paths.d.ts +8 -0
- package/dist/serve/paths.js +19 -4
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,128 +1,185 @@
|
|
|
1
1
|
# DAxTA
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Tested behavior. Trusted API docs.**
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
DAxTA docs — recorded request, response, Try-it
|
|
8
|
-
|
|
9
|
-
## What you get
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
| After tests | On the app |
|
|
13
|
-
| ------------------------------------- | -------------------------------------------------------- |
|
|
14
|
-
| OpenAPI + HTML from real hits | `/docs` on the same port as Nest |
|
|
15
|
-
| POSITIVE / INVALID / SEMANTIC / AUTH scenarios | Example picker uses the `when` clause only |
|
|
16
|
-
| DTO field map (required vs optional) | `DAXTA_DOCS=true|false` gate (like Swagger’s prod check) |
|
|
5
|
+
DAxTA generates and publishes API documentation from API behavior observed during automated tests.
|
|
17
6
|
|
|
7
|
+
```ts
|
|
8
|
+
import { apiDocs, generateApiDocs } from '@t0.labs/daxta';
|
|
18
9
|
|
|
19
|
-
|
|
10
|
+
await generateApiDocs();
|
|
11
|
+
apiDocs(app);
|
|
12
|
+
```
|
|
20
13
|
|
|
21
|
-
|
|
14
|
+
Swagger asks you to decorate controllers. DAxTA records what your tests actually call.
|
|
22
15
|
|
|
23
16
|
```text
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
Docs ready → http://localhost:3000/docs
|
|
17
|
+
Tests
|
|
18
|
+
↓
|
|
19
|
+
Observed API Behavior
|
|
20
|
+
↓
|
|
21
|
+
DAxTA
|
|
22
|
+
↓
|
|
23
|
+
Verified API Docs
|
|
24
|
+
↓
|
|
25
|
+
Hosted Documentation
|
|
34
26
|
```
|
|
35
27
|
|
|
36
|
-
|
|
37
|
-
2. **During the run** only traffic is recorded (disk flush). OpenAPI/HTML is rebuilt once when Jest finishes, from **this run’s hits only** (previous worker shards are cleared so examples do not stack).
|
|
38
|
-
3. `apiDocs(app)` in `main.ts` serves the generated viewer when `DAXTA_DOCS=true`.
|
|
39
|
-
|
|
28
|
+
The documentation shows what tests really exercise — not what the code claims to do.
|
|
40
29
|
|
|
30
|
+
## Install
|
|
41
31
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
Tek komut — dependency, `apiDocs(app)`, Jest plugin, `daxta.config.ts` ve sidebar tercihler:
|
|
32
|
+
One command — dependency, `apiDocs(app)`, Jest plugin, `daxta.config.ts`, and sidebar preferences:
|
|
45
33
|
|
|
46
34
|
```bash
|
|
47
35
|
pnpm dlx @t0.labs/daxta install
|
|
48
|
-
#
|
|
36
|
+
# or
|
|
49
37
|
npx @t0.labs/daxta install
|
|
50
38
|
```
|
|
51
39
|
|
|
52
|
-
|
|
53
|
-
`DAXTA_DOCS=true`
|
|
40
|
+
Install asks for the Nest entry, test script, sidebar folder order (`role-resource` / `resource-role`), `{id}` fold, and example label style.
|
|
41
|
+
`DAXTA_DOCS=true` is written to `.env` (created if missing).
|
|
54
42
|
|
|
55
|
-
|
|
43
|
+
Then:
|
|
56
44
|
|
|
57
45
|
```bash
|
|
58
|
-
pnpm run test:integration #
|
|
59
|
-
pnpm start:dev # app
|
|
46
|
+
pnpm run test:integration # generates API docs when Jest finishes
|
|
47
|
+
pnpm start:dev # API docs on the app port at /api-docs
|
|
60
48
|
```
|
|
61
49
|
|
|
62
50
|
```ts
|
|
63
51
|
import { apiDocs } from '@t0.labs/daxta';
|
|
64
52
|
|
|
65
|
-
apiDocs(app); // DAXTA_DOCS
|
|
53
|
+
apiDocs(app); // DAXTA_DOCS is required (true | false)
|
|
66
54
|
```
|
|
67
55
|
|
|
68
56
|
Flags: `--yes` · `--dry-run` · `--skip-main` · `--skip-dep` · `--main <path>` · `--fast`
|
|
69
57
|
|
|
70
|
-
##
|
|
58
|
+
## Uninstall
|
|
71
59
|
|
|
72
60
|
```bash
|
|
73
61
|
pnpm dlx @t0.labs/daxta uninstall
|
|
74
|
-
#
|
|
62
|
+
# or
|
|
75
63
|
npx @t0.labs/daxta uninstall
|
|
76
64
|
```
|
|
77
65
|
|
|
78
|
-
|
|
66
|
+
Removes:
|
|
79
67
|
|
|
80
68
|
- `apiDocs` + `@t0.labs/daxta` import (`main.ts`)
|
|
81
|
-
- Jest `setup` + `jest-reporter` (+ `globalSetup` when
|
|
82
|
-
- `daxta.config.*`
|
|
83
|
-
- `.gitignore` / `.env`
|
|
84
|
-
- `@t0.labs/daxta`
|
|
85
|
-
|
|
86
|
-
Flags: `--yes` · `--dry-run` · `--keep-dep` (paketi bırakıp sadece wiring’i sök) · `--fast`
|
|
69
|
+
- Jest `setup` + `jest-reporter` (+ `globalSetup` when DAxTA added it)
|
|
70
|
+
- `daxta.config.*` and `.daxta/` output
|
|
71
|
+
- DAxTA lines in `.gitignore` / `.env`
|
|
72
|
+
- `@t0.labs/daxta` package
|
|
87
73
|
|
|
74
|
+
Flags: `--yes` · `--dry-run` · `--keep-dep` (leave the package, unwind wiring only) · `--fast`
|
|
88
75
|
|
|
76
|
+
## How it works
|
|
89
77
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
78
|
+
```text
|
|
79
|
+
your Jest suite
|
|
80
|
+
│ supertest / superagent hits
|
|
81
|
+
▼
|
|
82
|
+
DAxTA records hits to disk
|
|
83
|
+
│ (no OpenAPI rebuild mid-run)
|
|
84
|
+
▼
|
|
85
|
+
onRunComplete → generate API docs
|
|
86
|
+
│
|
|
87
|
+
▼
|
|
88
|
+
API docs ready → http://localhost:3000/api-docs
|
|
89
|
+
```
|
|
95
90
|
|
|
96
|
-
|
|
91
|
+
1. **Install** attaches DAxTA as a Jest plugin (`setupFilesAfterEnv` + reporter, and `globalSetup` when you don’t already have one). Your existing `test:integration` stays the entrypoint — DAxTA does not wrap the process.
|
|
92
|
+
2. **During the run** only traffic is recorded. The API spec and HTML are generated once when Jest finishes, from **this run’s hits only**.
|
|
93
|
+
3. `apiDocs(app)` in `main.ts` serves the generated viewer when `DAXTA_DOCS=true`.
|
|
97
94
|
|
|
98
|
-
|
|
95
|
+
| After tests | On the app |
|
|
96
|
+
| --- | --- |
|
|
97
|
+
| OpenAPI + HTML from real hits | `/api-docs` on the same port as Nest |
|
|
98
|
+
| POSITIVE / INVALID / SEMANTIC / AUTH scenarios | Example picker uses the `when` clause only |
|
|
99
|
+
| DTO field map (required vs optional) | `DAXTA_DOCS=true\|false` gate |
|
|
99
100
|
|
|
100
101
|
## `DAXTA_DOCS` (required)
|
|
101
102
|
|
|
102
103
|
Same idea as Nest Swagger’s “don’t call `setup` in prod”:
|
|
103
104
|
|
|
104
105
|
```bash
|
|
105
|
-
DAXTA_DOCS=true # mount /docs (install writes this)
|
|
106
|
+
DAXTA_DOCS=true # mount /api-docs (install writes this)
|
|
106
107
|
DAXTA_DOCS=false # no-op (must still be set)
|
|
107
108
|
# unset / empty → throws — make the choice explicit
|
|
108
109
|
```
|
|
109
110
|
|
|
110
|
-
`false` does not remove `@t0.labs/daxta` from the Node image; it only skips mounting
|
|
111
|
+
`false` does not remove `@t0.labs/daxta` from the Node image; it only skips mounting API docs.
|
|
111
112
|
|
|
112
|
-
##
|
|
113
|
+
## Config
|
|
113
114
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
115
|
+
`daxta.config.ts`:
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
import { defineConfig } from '@t0.labs/daxta';
|
|
119
|
+
|
|
120
|
+
export default defineConfig({
|
|
121
|
+
specInfo: () => ({
|
|
122
|
+
title: 'Merchant API',
|
|
123
|
+
version: '1.0.0',
|
|
124
|
+
}),
|
|
125
|
+
baseUrl: 'http://localhost:3000',
|
|
126
|
+
docsPath: '/api-docs',
|
|
127
|
+
outDir: '.daxta/out',
|
|
128
|
+
viewerStoreFile: '.daxta/viewer-store.json',
|
|
129
|
+
envPresets: {
|
|
130
|
+
local: { baseUrl: 'http://localhost:3000' },
|
|
131
|
+
staging: { baseUrl: 'https://api.staging.example.com' },
|
|
132
|
+
production: { baseUrl: 'https://api.example.com' },
|
|
133
|
+
},
|
|
134
|
+
});
|
|
123
135
|
```
|
|
124
136
|
|
|
125
|
-
|
|
137
|
+
Generated artifacts live under `.daxta/`:
|
|
138
|
+
|
|
139
|
+
```text
|
|
140
|
+
.daxta/
|
|
141
|
+
├── out/
|
|
142
|
+
│ ├── openapi.json
|
|
143
|
+
│ └── openapi.html
|
|
144
|
+
└── viewer-store.json
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
DAxTA is the tool. The artifact is **API docs** (`openapi.json` + the HTML viewer). The hosted page title is your API title; the footer is a small **Generated by DAxTA**.
|
|
148
|
+
|
|
149
|
+
## CLI
|
|
150
|
+
|
|
151
|
+
```text
|
|
152
|
+
daxta generate
|
|
153
|
+
Generate API documentation from test execution.
|
|
154
|
+
|
|
155
|
+
daxta serve
|
|
156
|
+
Serve API documentation locally.
|
|
157
|
+
|
|
158
|
+
daxta install
|
|
159
|
+
Install DAxTA in this project.
|
|
160
|
+
|
|
161
|
+
daxta uninstall
|
|
162
|
+
Remove DAxTA from this project.
|
|
163
|
+
|
|
164
|
+
daxta migrate
|
|
165
|
+
Upgrade project wiring after a package bump.
|
|
166
|
+
|
|
167
|
+
daxta tree
|
|
168
|
+
Configure API docs sidebar layout.
|
|
169
|
+
|
|
170
|
+
daxta titles
|
|
171
|
+
Align test titles with API docs examples.
|
|
172
|
+
|
|
173
|
+
daxta fields
|
|
174
|
+
Export API field map.
|
|
175
|
+
|
|
176
|
+
daxta call
|
|
177
|
+
Send a Try-it request from the CLI.
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
`daxta build` is an alias of `daxta generate`.
|
|
181
|
+
|
|
182
|
+
### API docs presentation (`daxta install` / `daxta migrate` / `daxta tree`)
|
|
126
183
|
|
|
127
184
|
Company-wide choices (saved in `daxta.config.ts`):
|
|
128
185
|
|
|
@@ -137,26 +194,16 @@ OpenAPI path keys in the generated spec still follow the sidebar tree. Real URLs
|
|
|
137
194
|
|
|
138
195
|
### Try-it env / headers (persisted)
|
|
139
196
|
|
|
140
|
-
Env **presets** (multi-base) + header groups are editable in the docs UI.
|
|
141
|
-
|
|
142
|
-
Define company defaults in `daxta.config.ts`:
|
|
143
|
-
|
|
144
|
-
```ts
|
|
145
|
-
envPresets: {
|
|
146
|
-
local: { baseUrl: 'http://localhost:3000' },
|
|
147
|
-
staging: { baseUrl: 'https://api.staging.example.com' },
|
|
148
|
-
production: { baseUrl: 'https://api.example.com', variables: { apiKey: '' } },
|
|
149
|
-
},
|
|
150
|
-
```
|
|
197
|
+
Env **presets** (multi-base) + header groups are editable in the API docs UI.
|
|
151
198
|
|
|
152
|
-
-
|
|
153
|
-
- Serving the app only auto-fills **local** (or sole) preset — staging/production URLs are not overwritten
|
|
154
|
-
- First `daxta
|
|
199
|
+
- The picker shows each preset with its own `baseUrl` + variables + header groups
|
|
200
|
+
- Serving the app only auto-fills **local** (or sole) preset — staging/production URLs are not overwritten
|
|
201
|
+
- First `daxta generate` seeds `.daxta/viewer-store.json` from `envPresets` if the file is missing
|
|
155
202
|
- Runtime edits still persist via `GET/PUT {docsPath}/env.json`
|
|
156
203
|
|
|
157
204
|
Sidebar: expand the chevron on an endpoint to list recorded examples underneath; click one to open it in the workbench.
|
|
158
205
|
|
|
159
|
-
Export: download is **Postman Collection** (nested folders like the sidebar) plus, by default, the active Try-it **environment + header group** as a `.postman_environment.json`. Pick All / None / Success only for which examples to include.
|
|
206
|
+
Export: download is **Postman Collection** (nested folders like the sidebar) plus, by default, the active Try-it **environment + header group** as a `.postman_environment.json`. Pick All / None / Success only for which examples to include.
|
|
160
207
|
|
|
161
208
|
Example label (`status-title-case`):
|
|
162
209
|
|
|
@@ -164,9 +211,9 @@ Example label (`status-title-case`):
|
|
|
164
211
|
200 — Admin Find One Basket By Id API — returns basket with items when found by id
|
|
165
212
|
```
|
|
166
213
|
|
|
167
|
-
Then `daxta
|
|
214
|
+
Then `daxta generate` to refresh `/api-docs` and export.
|
|
168
215
|
|
|
169
|
-
## Test titles (docs / Postman names)
|
|
216
|
+
## Test titles (API docs / Postman names)
|
|
170
217
|
|
|
171
218
|
Readable `TEST_TITLE` (path stays after the em dash so DAxTA can still bind the route):
|
|
172
219
|
|
|
@@ -192,14 +239,14 @@ Suggested titles (method + path, never `:id` as a name):
|
|
|
192
239
|
|
|
193
240
|
Old `{path} [METHOD] (integration)` still parses. `daxta titles --yes` rewrites to the new form.
|
|
194
241
|
|
|
195
|
-
`it()` keeps a unique sentence; `/docs` examples take the part after `when` (groups match describe: POSITIVE CASES, SEMANTIC ERROR CASES, …):
|
|
242
|
+
`it()` keeps a unique sentence; `/api-docs` examples take the part after `when` (groups match describe: POSITIVE CASES, SEMANTIC ERROR CASES, …):
|
|
196
243
|
|
|
197
244
|
| Layer | Rule | Example |
|
|
198
245
|
| --- | --- | --- |
|
|
199
246
|
| Positive `it()` | `{creates\|returns\|updates\|…} … when {diff}` | `creates mock tbs TRNC record when cyprus payload shape` |
|
|
200
247
|
| Error `it()` | `returns error when {diff}` | `returns error when tax id already exists in mock TBS` |
|
|
201
248
|
| Invalid fields | leave interpolated | `` `${property} - should not be ${description}` `` |
|
|
202
|
-
|
|
|
249
|
+
| API docs / Postman | `{status} — {after when}` | `201 — cyprus payload shape` |
|
|
203
250
|
|
|
204
251
|
`--yes` / `a` rewrite **this case’s own text**, not one shared template. Interpolated `it(\`${…}\`)` is never rewritten.
|
|
205
252
|
|
|
@@ -209,16 +256,17 @@ daxta titles --yes # rewrite every hit with the recommended name
|
|
|
209
256
|
daxta titles --check # report only
|
|
210
257
|
```
|
|
211
258
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
259
|
## API
|
|
216
260
|
|
|
217
261
|
```ts
|
|
218
|
-
import { apiDocs, apiDocsHandler, serveApiDocs } from '@t0.labs/daxta';
|
|
262
|
+
import { apiDocs, apiDocsHandler, generateApiDocs, getApiDocUrl, getApiDocs, serveApiDocs } from '@t0.labs/daxta';
|
|
219
263
|
|
|
264
|
+
await generateApiDocs(); // OpenAPI spec + HTML from recorded test hits
|
|
220
265
|
apiDocs(app); // preferred — same origin as the API
|
|
221
266
|
app.use(apiDocsHandler()); // Express-style mount
|
|
222
267
|
serveApiDocs({ port: 5199 }); // standalone (CLI / rare)
|
|
268
|
+
getApiDocUrl(); // e.g. http://localhost:3000/api-docs
|
|
269
|
+
getApiDocs(); // { url, specPath, htmlPath }
|
|
223
270
|
```
|
|
224
271
|
|
|
272
|
+
Capture during tests is an implementation detail. The public surface is generate, then mount or serve.
|
package/assets/empty.html
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="utf-8" />
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
6
|
-
<title>
|
|
6
|
+
<title>API Documentation</title>
|
|
7
7
|
<link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+CiAgPHN0eWxlPgogICAgLmJnIHsgZmlsbDogI2ZmZmZmZjsgfQogICAgLmZnIHsgZmlsbDogIzExMTExMTsgfQogICAgLnJpbmcgeyBmaWxsOiBub25lOyBzdHJva2U6ICMxMTExMTE7IHN0cm9rZS13aWR0aDogMS4yNTsgfQogICAgQG1lZGlhIChwcmVmZXJzLWNvbG9yLXNjaGVtZTogZGFyaykgewogICAgICAuYmcgeyBmaWxsOiAjMTExMTExOyB9CiAgICAgIC5mZyB7IGZpbGw6ICNmZmZmZmY7IH0KICAgICAgLnJpbmcgeyBzdHJva2U6ICNmZmZmZmY7IH0KICAgIH0KICA8L3N0eWxlPgogIDxyZWN0IGNsYXNzPSJiZyIgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIvPgogIDxyZWN0IGNsYXNzPSJyaW5nIiB4PSIwLjYiIHk9IjAuNiIgd2lkdGg9IjMwLjgiIGhlaWdodD0iMzAuOCIgcng9IjYuNCIvPgogIDxwYXRoIGNsYXNzPSJmZyIgZD0iTTQuMiA1LjIgMTQuMiA4Ljh2NC4yQTQuMiA0LjIgMCAwIDEgMTQuMiAyMS40djRMNC4yIDI2LjhaIi8+CiAgPHBhdGggY2xhc3M9ImZnIiBkPSJNMjcuOCA1LjIgMTcuOCA4Ljh2NC4yQTQuMiA0LjIgMCAwIDAgMTcuOCAyMS40djRMMjcuOCAyNi44WiIvPgo8L3N2Zz4K" />
|
|
8
8
|
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
|
9
9
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
|
@@ -134,16 +134,16 @@
|
|
|
134
134
|
</head>
|
|
135
135
|
<body>
|
|
136
136
|
<header class="topnav">
|
|
137
|
-
<span class="nav-meta">/docs</span>
|
|
137
|
+
<span class="nav-meta">/api-docs</span>
|
|
138
138
|
</header>
|
|
139
139
|
<main class="stage">
|
|
140
140
|
<div class="panel">
|
|
141
141
|
<p class="kicker">Waiting</p>
|
|
142
|
-
<h1>No documentation yet</h1>
|
|
142
|
+
<h1>No API documentation yet</h1>
|
|
143
143
|
<p>This page publishes when API traffic has been recorded. Run your integration tests, then refresh.</p>
|
|
144
144
|
<ol class="steps">
|
|
145
145
|
<li><span class="n">1</span><span>Run the integration suite that hits your API.</span></li>
|
|
146
|
-
<li><span class="n">2</span><span>DAxTA writes
|
|
146
|
+
<li><span class="n">2</span><span>DAxTA writes API docs from those requests and responses.</span></li>
|
|
147
147
|
<li><span class="n">3</span><span>Reload this page to open the workbench.</span></li>
|
|
148
148
|
</ol>
|
|
149
149
|
<pre class="cmd">pnpm run test:integration</pre>
|
package/assets/example.html
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="utf-8" />
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
6
|
-
<title>
|
|
6
|
+
<title>API Documentation</title>
|
|
7
7
|
<link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+CiAgPHN0eWxlPgogICAgLmJnIHsgZmlsbDogI2ZmZmZmZjsgfQogICAgLmZnIHsgZmlsbDogIzExMTExMTsgfQogICAgLnJpbmcgeyBmaWxsOiBub25lOyBzdHJva2U6ICMxMTExMTE7IHN0cm9rZS13aWR0aDogMS4yNTsgfQogICAgQG1lZGlhIChwcmVmZXJzLWNvbG9yLXNjaGVtZTogZGFyaykgewogICAgICAuYmcgeyBmaWxsOiAjMTExMTExOyB9CiAgICAgIC5mZyB7IGZpbGw6ICNmZmZmZmY7IH0KICAgICAgLnJpbmcgeyBzdHJva2U6ICNmZmZmZmY7IH0KICAgIH0KICA8L3N0eWxlPgogIDxyZWN0IGNsYXNzPSJiZyIgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIvPgogIDxyZWN0IGNsYXNzPSJyaW5nIiB4PSIwLjYiIHk9IjAuNiIgd2lkdGg9IjMwLjgiIGhlaWdodD0iMzAuOCIgcng9IjYuNCIvPgogIDxwYXRoIGNsYXNzPSJmZyIgZD0iTTQuMiA1LjIgMTQuMiA4Ljh2NC4yQTQuMiA0LjIgMCAwIDEgMTQuMiAyMS40djRMNC4yIDI2LjhaIi8+CiAgPHBhdGggY2xhc3M9ImZnIiBkPSJNMjcuOCA1LjIgMTcuOCA4Ljh2NC4yQTQuMiA0LjIgMCAwIDAgMTcuOCAyMS40djRMMjcuOCAyNi44WiIvPgo8L3N2Zz4K" />
|
|
8
8
|
<link rel="apple-touch-icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+CiAgPHN0eWxlPgogICAgLmJnIHsgZmlsbDogI2ZmZmZmZjsgfQogICAgLmZnIHsgZmlsbDogIzExMTExMTsgfQogICAgLnJpbmcgeyBmaWxsOiBub25lOyBzdHJva2U6ICMxMTExMTE7IHN0cm9rZS13aWR0aDogMS4yNTsgfQogICAgQG1lZGlhIChwcmVmZXJzLWNvbG9yLXNjaGVtZTogZGFyaykgewogICAgICAuYmcgeyBmaWxsOiAjMTExMTExOyB9CiAgICAgIC5mZyB7IGZpbGw6ICNmZmZmZmY7IH0KICAgICAgLnJpbmcgeyBzdHJva2U6ICNmZmZmZmY7IH0KICAgIH0KICA8L3N0eWxlPgogIDxyZWN0IGNsYXNzPSJiZyIgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIvPgogIDxyZWN0IGNsYXNzPSJyaW5nIiB4PSIwLjYiIHk9IjAuNiIgd2lkdGg9IjMwLjgiIGhlaWdodD0iMzAuOCIgcng9IjYuNCIvPgogIDxwYXRoIGNsYXNzPSJmZyIgZD0iTTQuMiA1LjIgMTQuMiA4Ljh2NC4yQTQuMiA0LjIgMCAwIDEgMTQuMiAyMS40djRMNC4yIDI2LjhaIi8+CiAgPHBhdGggY2xhc3M9ImZnIiBkPSJNMjcuOCA1LjIgMTcuOCA4Ljh2NC4yQTQuMiA0LjIgMCAwIDAgMTcuOCAyMS40djRMMjcuOCAyNi44WiIvPgo8L3N2Zz4K" />
|
|
9
9
|
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
|
@@ -1305,7 +1305,7 @@
|
|
|
1305
1305
|
"x-viewer": {
|
|
1306
1306
|
"workspace": "token-x",
|
|
1307
1307
|
"baseUrl": "http://localhost:3000",
|
|
1308
|
-
"docsPath": "/docs",
|
|
1308
|
+
"docsPath": "/api-docs",
|
|
1309
1309
|
"envPresets": {
|
|
1310
1310
|
"local": { "baseUrl": "http://localhost:3000" }
|
|
1311
1311
|
}
|
|
@@ -1504,7 +1504,7 @@
|
|
|
1504
1504
|
const viewer = spec["x-viewer"] || {};
|
|
1505
1505
|
const workspace = (spec.info && spec.info["x-workspace"]) || viewer.workspace || "";
|
|
1506
1506
|
const defaultBaseUrlFromSpec = String((viewer.baseUrl || (spec.servers && spec.servers[0] && spec.servers[0].url) || "http://localhost:3000")).replace(/\/$/, "");
|
|
1507
|
-
const docsPathSuffix = String(viewer.docsPath || "/docs").replace(/\/$/, "") || "/docs";
|
|
1507
|
+
const docsPathSuffix = String(viewer.docsPath || "/api-docs").replace(/\/$/, "") || "/api-docs";
|
|
1508
1508
|
|
|
1509
1509
|
const inferBaseUrlFromLocation = () => {
|
|
1510
1510
|
if (typeof location === "undefined") return null;
|
|
@@ -1524,9 +1524,9 @@
|
|
|
1524
1524
|
};
|
|
1525
1525
|
|
|
1526
1526
|
const locationBaseUrl = inferBaseUrlFromLocation();
|
|
1527
|
-
// Prefer the URL that is serving the viewer (strip
|
|
1527
|
+
// Prefer the URL that is serving the viewer (strip the docs path), else fall back to spec.
|
|
1528
1528
|
const defaultBaseUrl = locationBaseUrl || defaultBaseUrlFromSpec;
|
|
1529
|
-
const title = (spec.info && spec.info.title) || "API
|
|
1529
|
+
const title = (spec.info && spec.info.title) || "API Documentation";
|
|
1530
1530
|
const STORE_KEY = "openapi-docs-env:" + (workspace || "default");
|
|
1531
1531
|
const SIDEBAR_STORE_KEY = "openapi-docs-sidebar:" + (workspace || "default");
|
|
1532
1532
|
const SIDEBAR_MIN = 200;
|
|
@@ -2258,7 +2258,7 @@
|
|
|
2258
2258
|
};
|
|
2259
2259
|
};
|
|
2260
2260
|
|
|
2261
|
-
document.title = title
|
|
2261
|
+
document.title = title || "API Documentation";
|
|
2262
2262
|
const brandEl = document.getElementById("brand");
|
|
2263
2263
|
if (brandEl) brandEl.textContent = title;
|
|
2264
2264
|
const specVersion = (spec.info && spec.info.version) || "";
|
|
@@ -2512,7 +2512,7 @@
|
|
|
2512
2512
|
}
|
|
2513
2513
|
return {
|
|
2514
2514
|
id: typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : String(Date.now()),
|
|
2515
|
-
name: (workspace || title || "
|
|
2515
|
+
name: (workspace || title || "API") + " · " + store.activeEnv,
|
|
2516
2516
|
values,
|
|
2517
2517
|
_postman_variable_scope: "environment",
|
|
2518
2518
|
_postman_exported_at: new Date().toISOString(),
|
|
@@ -2685,8 +2685,8 @@
|
|
|
2685
2685
|
return {
|
|
2686
2686
|
info: {
|
|
2687
2687
|
_postman_id: typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : String(Date.now()),
|
|
2688
|
-
name: (openapi.info && openapi.info.title) || workspace || title || "
|
|
2689
|
-
description: (openapi.info && openapi.info.description) || "Exported from
|
|
2688
|
+
name: (openapi.info && openapi.info.title) || workspace || title || "API",
|
|
2689
|
+
description: (openapi.info && openapi.info.description) || "Exported from API docs with named examples",
|
|
2690
2690
|
schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
|
|
2691
2691
|
},
|
|
2692
2692
|
item,
|
|
@@ -3582,7 +3582,7 @@
|
|
|
3582
3582
|
body: undefined,
|
|
3583
3583
|
error:
|
|
3584
3584
|
message +
|
|
3585
|
-
"\n\nTip: open docs at the same app port: http://localhost:3000
|
|
3585
|
+
"\n\nTip: open API docs at the same app port: http://localhost:3000" + docsPathSuffix,
|
|
3586
3586
|
};
|
|
3587
3587
|
}
|
|
3588
3588
|
renderMain();
|
package/assets/viewer.html
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="utf-8" />
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
6
|
-
<title>
|
|
6
|
+
<title>API Documentation</title>
|
|
7
7
|
<link rel="icon" href="__FAVICON_DATA_URI__" />
|
|
8
8
|
<link rel="apple-touch-icon" href="__FAVICON_DATA_URI__" />
|
|
9
9
|
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
|
@@ -1302,7 +1302,7 @@
|
|
|
1302
1302
|
const viewer = spec["x-viewer"] || {};
|
|
1303
1303
|
const workspace = (spec.info && spec.info["x-workspace"]) || viewer.workspace || "";
|
|
1304
1304
|
const defaultBaseUrlFromSpec = String((viewer.baseUrl || (spec.servers && spec.servers[0] && spec.servers[0].url) || "http://localhost:3000")).replace(/\/$/, "");
|
|
1305
|
-
const docsPathSuffix = String(viewer.docsPath || "/docs").replace(/\/$/, "") || "/docs";
|
|
1305
|
+
const docsPathSuffix = String(viewer.docsPath || "/api-docs").replace(/\/$/, "") || "/api-docs";
|
|
1306
1306
|
|
|
1307
1307
|
const inferBaseUrlFromLocation = () => {
|
|
1308
1308
|
if (typeof location === "undefined") return null;
|
|
@@ -1322,9 +1322,9 @@
|
|
|
1322
1322
|
};
|
|
1323
1323
|
|
|
1324
1324
|
const locationBaseUrl = inferBaseUrlFromLocation();
|
|
1325
|
-
// Prefer the URL that is serving the viewer (strip
|
|
1325
|
+
// Prefer the URL that is serving the viewer (strip the docs path), else fall back to spec.
|
|
1326
1326
|
const defaultBaseUrl = locationBaseUrl || defaultBaseUrlFromSpec;
|
|
1327
|
-
const title = (spec.info && spec.info.title) || "API
|
|
1327
|
+
const title = (spec.info && spec.info.title) || "API Documentation";
|
|
1328
1328
|
const STORE_KEY = "openapi-docs-env:" + (workspace || "default");
|
|
1329
1329
|
const SIDEBAR_STORE_KEY = "openapi-docs-sidebar:" + (workspace || "default");
|
|
1330
1330
|
const SIDEBAR_MIN = 200;
|
|
@@ -2056,7 +2056,7 @@
|
|
|
2056
2056
|
};
|
|
2057
2057
|
};
|
|
2058
2058
|
|
|
2059
|
-
document.title = title
|
|
2059
|
+
document.title = title || "API Documentation";
|
|
2060
2060
|
const brandEl = document.getElementById("brand");
|
|
2061
2061
|
if (brandEl) brandEl.textContent = title;
|
|
2062
2062
|
const specVersion = (spec.info && spec.info.version) || "";
|
|
@@ -2310,7 +2310,7 @@
|
|
|
2310
2310
|
}
|
|
2311
2311
|
return {
|
|
2312
2312
|
id: typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : String(Date.now()),
|
|
2313
|
-
name: (workspace || title || "
|
|
2313
|
+
name: (workspace || title || "API") + " · " + store.activeEnv,
|
|
2314
2314
|
values,
|
|
2315
2315
|
_postman_variable_scope: "environment",
|
|
2316
2316
|
_postman_exported_at: new Date().toISOString(),
|
|
@@ -2483,8 +2483,8 @@
|
|
|
2483
2483
|
return {
|
|
2484
2484
|
info: {
|
|
2485
2485
|
_postman_id: typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : String(Date.now()),
|
|
2486
|
-
name: (openapi.info && openapi.info.title) || workspace || title || "
|
|
2487
|
-
description: (openapi.info && openapi.info.description) || "Exported from
|
|
2486
|
+
name: (openapi.info && openapi.info.title) || workspace || title || "API",
|
|
2487
|
+
description: (openapi.info && openapi.info.description) || "Exported from API docs with named examples",
|
|
2488
2488
|
schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
|
|
2489
2489
|
},
|
|
2490
2490
|
item,
|
|
@@ -3380,7 +3380,7 @@
|
|
|
3380
3380
|
body: undefined,
|
|
3381
3381
|
error:
|
|
3382
3382
|
message +
|
|
3383
|
-
"\n\nTip: open docs at the same app port: http://localhost:3000
|
|
3383
|
+
"\n\nTip: open API docs at the same app port: http://localhost:3000" + docsPathSuffix,
|
|
3384
3384
|
};
|
|
3385
3385
|
}
|
|
3386
3386
|
renderMain();
|
|
@@ -24,5 +24,7 @@ export declare function buildDaxtaSpec(options?: {
|
|
|
24
24
|
requireHits?: boolean;
|
|
25
25
|
html?: boolean;
|
|
26
26
|
}): BuildResult;
|
|
27
|
-
/**
|
|
27
|
+
/** Generate API documentation (OpenAPI spec + HTML viewer) from recorded test execution. */
|
|
28
|
+
export declare const generateApiDocs: typeof buildDaxtaSpec;
|
|
29
|
+
/** @deprecated Use `generateApiDocs` */
|
|
28
30
|
export declare const buildOpenApi: typeof buildDaxtaSpec;
|
package/dist/build/build-spec.js
CHANGED
|
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
-
exports.buildOpenApi = void 0;
|
|
36
|
+
exports.buildOpenApi = exports.generateApiDocs = void 0;
|
|
37
37
|
exports.loadHits = loadHits;
|
|
38
38
|
exports.buildDaxtaSpec = buildDaxtaSpec;
|
|
39
39
|
const fs_1 = require("fs");
|
|
@@ -75,7 +75,7 @@ function readPackageMeta() {
|
|
|
75
75
|
};
|
|
76
76
|
}
|
|
77
77
|
catch {
|
|
78
|
-
return { title: 'API', version: '0.0.0', description: 'Generated from
|
|
78
|
+
return { title: 'API', version: '0.0.0', description: 'Generated from observed test execution.' };
|
|
79
79
|
}
|
|
80
80
|
}
|
|
81
81
|
function specInfo() {
|
|
@@ -807,7 +807,7 @@ function buildDaxtaSpec(options = {}) {
|
|
|
807
807
|
};
|
|
808
808
|
if (!options.silent) {
|
|
809
809
|
if (!changed) {
|
|
810
|
-
console.log(`
|
|
810
|
+
console.log(`API spec unchanged (${hits.length} hits, ${operations} operations — ${unchanged} kept as-is)`);
|
|
811
811
|
}
|
|
812
812
|
else {
|
|
813
813
|
console.log(`Wrote ${(0, paths_1.getSpecJsonPath)()} from ${hits.length} hits (${operations} operations — ${updated} updated, ${unchanged} unchanged)`);
|
|
@@ -816,5 +816,7 @@ function buildDaxtaSpec(options = {}) {
|
|
|
816
816
|
}
|
|
817
817
|
return result;
|
|
818
818
|
}
|
|
819
|
-
/**
|
|
819
|
+
/** Generate API documentation (OpenAPI spec + HTML viewer) from recorded test execution. */
|
|
820
|
+
exports.generateApiDocs = buildDaxtaSpec;
|
|
821
|
+
/** @deprecated Use `generateApiDocs` */
|
|
820
822
|
exports.buildOpenApi = buildDaxtaSpec;
|
package/dist/cli/install.js
CHANGED
|
@@ -110,17 +110,20 @@ function writeConfig(cwd, dryRun) {
|
|
|
110
110
|
const body = `import { defineConfig } from '@t0.labs/daxta';
|
|
111
111
|
|
|
112
112
|
export default defineConfig({
|
|
113
|
+
specInfo: () => ({
|
|
114
|
+
title: 'API',
|
|
115
|
+
version: '1.0.0',
|
|
116
|
+
}),
|
|
113
117
|
workspace: 'API',
|
|
114
118
|
baseUrl: 'http://localhost:3000',
|
|
115
119
|
controllersRoot: 'src',
|
|
116
|
-
outDir: 'daxta/out',
|
|
117
|
-
docsPath: '/docs',
|
|
120
|
+
outDir: '.daxta/out',
|
|
121
|
+
docsPath: '/api-docs',
|
|
118
122
|
treeLayout: 'role-resource',
|
|
119
123
|
treeSkipParams: true,
|
|
120
124
|
exampleLabelStyle: 'status-title-case',
|
|
121
|
-
fieldsFile: 'daxta/out/
|
|
122
|
-
viewerStoreFile: 'daxta/viewer-store.json',
|
|
123
|
-
// Multi-base Try-it presets (docs env picker). Secrets stay in viewer-store / UI.
|
|
125
|
+
fieldsFile: '.daxta/out/fields.json',
|
|
126
|
+
viewerStoreFile: '.daxta/viewer-store.json',
|
|
124
127
|
envPresets: {
|
|
125
128
|
local: { baseUrl: 'http://localhost:3000' },
|
|
126
129
|
staging: { baseUrl: 'https://api.staging.example.com' },
|
|
@@ -134,7 +137,7 @@ export default defineConfig({
|
|
|
134
137
|
}
|
|
135
138
|
function ensureGitignore(cwd, dryRun) {
|
|
136
139
|
const gitignorePath = path.join(cwd, '.gitignore');
|
|
137
|
-
const entries = ['daxta/out/', 'daxta/viewer-store.json', '**/.jest.daxta.runtime.json'];
|
|
140
|
+
const entries = ['.daxta/out/', '.daxta/viewer-store.json', '**/.jest.daxta.runtime.json'];
|
|
138
141
|
if (!(0, fs_1.existsSync)(gitignorePath)) {
|
|
139
142
|
if (!dryRun)
|
|
140
143
|
(0, fs_1.writeFileSync)(gitignorePath, `${entries.join('\n')}\n`);
|
|
@@ -145,7 +148,7 @@ function ensureGitignore(cwd, dryRun) {
|
|
|
145
148
|
const added = [];
|
|
146
149
|
let next = text;
|
|
147
150
|
for (const entry of entries) {
|
|
148
|
-
if (lines.has(entry) || lines.has('daxta/') || (entry === 'daxta/out/' && lines.has('daxta/out')))
|
|
151
|
+
if (lines.has(entry) || lines.has('.daxta/') || lines.has('daxta/') || (entry === '.daxta/out/' && (lines.has('.daxta/out') || lines.has('daxta/out/'))))
|
|
149
152
|
continue;
|
|
150
153
|
next = next.endsWith('\n') ? `${next}${entry}\n` : `${next}\n${entry}\n`;
|
|
151
154
|
added.push(entry);
|
|
@@ -225,7 +228,7 @@ async function installDaxta(options = {}) {
|
|
|
225
228
|
await (0, ui_1.step)('Package dependency', () => 'already installed — skip add', { paceMs, n: 1, of });
|
|
226
229
|
}
|
|
227
230
|
}
|
|
228
|
-
(0, ui_1.phase)(2, of, 'Workspace files', 'config, gitignore, docs env flag');
|
|
231
|
+
(0, ui_1.phase)(2, of, 'Workspace files', 'config, gitignore, API docs env flag');
|
|
229
232
|
await (0, ui_1.step)('Write daxta.config.ts', () => {
|
|
230
233
|
const { created, rel } = writeConfig(cwd, dryRun);
|
|
231
234
|
return created ? `created ${rel}` : `exists · ${rel}`;
|
|
@@ -246,8 +249,8 @@ async function installDaxta(options = {}) {
|
|
|
246
249
|
}, { paceMs, n: 2, of });
|
|
247
250
|
await (0, ui_1.step)('Prepare output dir', () => {
|
|
248
251
|
if (!dryRun)
|
|
249
|
-
(0, fs_1.mkdirSync)(path.join(cwd, 'daxta', 'out'), { recursive: true });
|
|
250
|
-
return 'daxta/out';
|
|
252
|
+
(0, fs_1.mkdirSync)(path.join(cwd, '.daxta', 'out'), { recursive: true });
|
|
253
|
+
return '.daxta/out';
|
|
251
254
|
}, { paceMs, n: 2, of });
|
|
252
255
|
await (0, ui_1.step)('Update .gitignore', () => {
|
|
253
256
|
const notes = ensureGitignore(cwd, dryRun);
|
|
@@ -334,14 +337,14 @@ async function installDaxta(options = {}) {
|
|
|
334
337
|
else {
|
|
335
338
|
await (0, ui_1.step)('Attach test hooks', () => 'skipped', { paceMs, n: 4, of });
|
|
336
339
|
}
|
|
337
|
-
(0, ui_1.phase)(5, of, '
|
|
340
|
+
(0, ui_1.phase)(5, of, 'API docs taste', 'sidebar folders + test titles for the viewer');
|
|
338
341
|
if (!dryRun) {
|
|
339
342
|
await (0, tree_1.runTreeWizard)({ embedded: true, yes: Boolean(options.yes) });
|
|
340
343
|
await (0, titles_1.runTitleCheck)({ cwd, yes: Boolean(options.yes) });
|
|
341
344
|
}
|
|
342
345
|
(0, ui_1.box)('Ready', [
|
|
343
346
|
`${ui_1.c.mint('✔')} ${ui_1.c.bold(project)} · DAxTA ${ui_1.c.gold(`v${version}`)}`,
|
|
344
|
-
`${ui_1.c.dim('docs')}
|
|
347
|
+
`${ui_1.c.dim('api docs')} ${ui_1.c.ice('/api-docs')} · ${ui_1.c.ice('DAXTA_DOCS=true')}`,
|
|
345
348
|
`${ui_1.c.dim('tests')} same script — titles first, spec after`,
|
|
346
349
|
`${ui_1.c.dim('retune')} ${ui_1.c.ice('daxta tree')} · ${ui_1.c.ice('daxta titles')}`,
|
|
347
350
|
]);
|
|
@@ -353,7 +356,7 @@ async function installDaxta(options = {}) {
|
|
|
353
356
|
},
|
|
354
357
|
{
|
|
355
358
|
cmd: `${pm} start:dev`,
|
|
356
|
-
why: 'open /docs (DAXTA_DOCS already in .env)',
|
|
359
|
+
why: 'open /api-docs (DAXTA_DOCS already in .env)',
|
|
357
360
|
},
|
|
358
361
|
]);
|
|
359
362
|
}
|
package/dist/cli/main.js
CHANGED
|
@@ -15,24 +15,24 @@ const ui_1 = require("./ui");
|
|
|
15
15
|
function usage() {
|
|
16
16
|
const cmd = (name) => ui_1.c.bold(ui_1.c.ice(name));
|
|
17
17
|
console.log('');
|
|
18
|
-
console.log(` ${ui_1.c.bold(ui_1.c.ice('DAxTA'))}
|
|
18
|
+
console.log(` ${ui_1.c.bold(ui_1.c.ice('DAxTA'))}`);
|
|
19
|
+
console.log(` ${ui_1.c.dim('Tested behavior. Trusted API docs.')}`);
|
|
19
20
|
console.log('');
|
|
20
21
|
console.log(` ${ui_1.c.gold('Setup')}`);
|
|
21
|
-
console.log(` ${cmd('daxta install')}
|
|
22
|
-
console.log(` ${cmd('daxta
|
|
23
|
-
console.log(` ${cmd('daxta
|
|
24
|
-
console.log(` ${cmd('daxta migrate')} ${ui_1.c.dim('[--yes]')}`);
|
|
22
|
+
console.log(` ${cmd('daxta install')} ${ui_1.c.dim('Install DAxTA in this project')}`);
|
|
23
|
+
console.log(` ${cmd('daxta uninstall')} ${ui_1.c.dim('Remove DAxTA from this project')}`);
|
|
24
|
+
console.log(` ${cmd('daxta migrate')} ${ui_1.c.dim('Upgrade project wiring after a package bump')}`);
|
|
25
25
|
console.log('');
|
|
26
|
-
console.log(` ${ui_1.c.gold('
|
|
27
|
-
console.log(` ${cmd('daxta
|
|
28
|
-
console.log(` ${cmd('daxta
|
|
29
|
-
console.log(` ${cmd('daxta
|
|
30
|
-
console.log(` ${cmd('daxta
|
|
31
|
-
console.log(` ${cmd('daxta
|
|
26
|
+
console.log(` ${ui_1.c.gold('API docs')}`);
|
|
27
|
+
console.log(` ${cmd('daxta generate')} ${ui_1.c.dim('Generate API documentation from test execution')}`);
|
|
28
|
+
console.log(` ${cmd('daxta serve')} ${ui_1.c.dim('Serve API documentation locally')}`);
|
|
29
|
+
console.log(` ${cmd('daxta tree')} ${ui_1.c.dim('Configure API docs sidebar layout')}`);
|
|
30
|
+
console.log(` ${cmd('daxta titles')} ${ui_1.c.dim('Align test titles with API docs examples')}`);
|
|
31
|
+
console.log(` ${cmd('daxta test')} ${ui_1.c.dim('Run the project test script (Jest stays parent)')}`);
|
|
32
32
|
console.log('');
|
|
33
33
|
console.log(` ${ui_1.c.gold('Try-it')}`);
|
|
34
|
-
console.log(` ${cmd('daxta fields')}
|
|
35
|
-
console.log(` ${cmd('daxta call')}
|
|
34
|
+
console.log(` ${cmd('daxta fields')} ${ui_1.c.dim('Export API field map')}`);
|
|
35
|
+
console.log(` ${cmd('daxta call')} ${ui_1.c.dim('Send a Try-it request from the CLI')}`);
|
|
36
36
|
console.log('');
|
|
37
37
|
console.log(` ${ui_1.c.mint('First time')} ${ui_1.c.ice('pnpm dlx @t0.labs/daxta install')}`);
|
|
38
38
|
console.log('');
|
|
@@ -126,8 +126,8 @@ async function main() {
|
|
|
126
126
|
await (0, test_1.runDaxtaTest)({ argv });
|
|
127
127
|
return;
|
|
128
128
|
}
|
|
129
|
-
if (command === 'build') {
|
|
130
|
-
(0, build_spec_1.
|
|
129
|
+
if (command === 'generate' || command === 'build') {
|
|
130
|
+
(0, build_spec_1.generateApiDocs)({ requireHits: true });
|
|
131
131
|
return;
|
|
132
132
|
}
|
|
133
133
|
if (command === 'serve') {
|
package/dist/cli/migrate.js
CHANGED
|
@@ -181,9 +181,9 @@ function migrateMainApiDocs(cwd) {
|
|
|
181
181
|
function migrateConfigDefaults(configPath, configText) {
|
|
182
182
|
const notes = [];
|
|
183
183
|
const fields = readStringField(configText, 'fieldsFile');
|
|
184
|
-
const outDir = readStringField(configText, 'outDir') || 'daxta/out';
|
|
184
|
+
const outDir = readStringField(configText, 'outDir') || '.daxta/out';
|
|
185
185
|
if (fields === 'daxta.fields.json' || fields === './daxta.fields.json') {
|
|
186
|
-
const next = `${outDir.replace(/\\/g, '/').replace(/\/$/, '')}/
|
|
186
|
+
const next = `${outDir.replace(/\\/g, '/').replace(/\/$/, '')}/fields.json`;
|
|
187
187
|
if (upsertConfigField(configPath, 'fieldsFile', next)) {
|
|
188
188
|
notes.push(`fieldsFile → ${next}`);
|
|
189
189
|
}
|
package/dist/cli/titles.js
CHANGED
|
@@ -128,17 +128,17 @@ async function runTitleCheck(options) {
|
|
|
128
128
|
(0, scan_1.printNamingFindings)(report, ui_1.c);
|
|
129
129
|
return options.strict ? 1 : 0;
|
|
130
130
|
}
|
|
131
|
-
(0, ui_1.banner)('Test naming', 'runs before Jest — docs / Postman labels');
|
|
131
|
+
(0, ui_1.banner)('Test naming', 'runs before Jest — API docs / Postman labels');
|
|
132
132
|
console.log(` ${ui_1.c.dim('Title')} Create Mock Tbs — POST /v1/admin/mock-tbs`);
|
|
133
133
|
console.log(` ${ui_1.c.dim('it()+')} creates mock tbs when cyprus payload shape`);
|
|
134
134
|
console.log(` ${ui_1.c.dim('it()-')} returns error when tax id already exists`);
|
|
135
|
-
console.log(` ${ui_1.c.dim('
|
|
135
|
+
console.log(` ${ui_1.c.dim('label')} 201 — cyprus payload shape`);
|
|
136
136
|
console.log(` ${ui_1.c.gold(String(total))} to review — ${ui_1.c.ice('y')} one recommended, ${ui_1.c.ice('a')} all remaining, ${ui_1.c.ice('s')} skip.`);
|
|
137
137
|
let written = 0;
|
|
138
138
|
let skipped = 0;
|
|
139
139
|
for (let i = 0; i < report.titles.length; i += 1) {
|
|
140
140
|
const finding = report.titles[i];
|
|
141
|
-
const choice = await pickFromSuggestions(finding, `docs would show ${finding.path}`, test_title_1.isHumanOperationTitle);
|
|
141
|
+
const choice = await pickFromSuggestions(finding, `API docs would show ${finding.path}`, test_title_1.isHumanOperationTitle);
|
|
142
142
|
if (choice === 'all') {
|
|
143
143
|
const rest = applyAllRecommended(cwd, report.titles, report.cases, i, 0);
|
|
144
144
|
written += rest.written;
|
package/dist/cli/tree.d.ts
CHANGED
|
@@ -5,6 +5,6 @@ export type TreeWizardOptions = {
|
|
|
5
5
|
yes?: boolean;
|
|
6
6
|
};
|
|
7
7
|
/**
|
|
8
|
-
* Company docs presentation wizard — install / migrate / `daxta tree`.
|
|
8
|
+
* Company API docs presentation wizard — install / migrate / `daxta tree`.
|
|
9
9
|
*/
|
|
10
10
|
export declare function runTreeWizard(options?: TreeWizardOptions): Promise<void>;
|
package/dist/cli/tree.js
CHANGED
|
@@ -169,7 +169,7 @@ async function pickSegments(pathTemplate, layout, skipParams) {
|
|
|
169
169
|
return typed.split(/›|>|,|\s+/).map((part) => part.trim()).filter(Boolean);
|
|
170
170
|
}
|
|
171
171
|
/**
|
|
172
|
-
* Company docs presentation wizard — install / migrate / `daxta tree`.
|
|
172
|
+
* Company API docs presentation wizard — install / migrate / `daxta tree`.
|
|
173
173
|
*/
|
|
174
174
|
async function runTreeWizard(options = {}) {
|
|
175
175
|
if (options.yes || !process.stdin.isTTY) {
|
|
@@ -178,14 +178,14 @@ async function runTreeWizard(options = {}) {
|
|
|
178
178
|
return;
|
|
179
179
|
}
|
|
180
180
|
if (!options.embedded)
|
|
181
|
-
(0, ui_1.banner)('DAxTA tree', 'docs presentation');
|
|
181
|
+
(0, ui_1.banner)('DAxTA tree', 'API docs presentation');
|
|
182
182
|
const configPath = (0, config_edit_1.findDaxtaConfigPath)();
|
|
183
183
|
if (!configPath)
|
|
184
184
|
throw new Error('No daxta.config.ts found. Run `daxta install` first.');
|
|
185
185
|
(0, config_1.resetConfig)();
|
|
186
186
|
const config = (0, config_1.getConfig)(true);
|
|
187
187
|
console.log('');
|
|
188
|
-
console.log(` ${ui_1.c.gold(ui_1.c.bold('?'))} ${ui_1.c.bold('
|
|
188
|
+
console.log(` ${ui_1.c.gold(ui_1.c.bold('?'))} ${ui_1.c.bold('API docs presentation')} ${ui_1.c.dim('— sidebar + OpenAPI export')}`);
|
|
189
189
|
let layout = (0, config_1.normalizeTreeLayout)(options.layout === 'resource-first' || options.layout === 'resource-role'
|
|
190
190
|
? 'resource-role'
|
|
191
191
|
: options.layout === 'url-order' || options.layout === 'role-resource'
|
|
@@ -219,7 +219,7 @@ async function runTreeWizard(options = {}) {
|
|
|
219
219
|
}
|
|
220
220
|
if (!options.embedded) {
|
|
221
221
|
console.log(` ${ui_1.c.dim('saved')} ${configPath}`);
|
|
222
|
-
console.log(` ${ui_1.c.dim('refresh')} ${ui_1.c.ice('daxta
|
|
222
|
+
console.log(` ${ui_1.c.dim('refresh')} ${ui_1.c.ice('daxta generate')}`);
|
|
223
223
|
console.log('');
|
|
224
224
|
}
|
|
225
225
|
}
|
package/dist/cli/ui.js
CHANGED
|
@@ -74,7 +74,7 @@ function divider(width = 52) {
|
|
|
74
74
|
}
|
|
75
75
|
function splash(options) {
|
|
76
76
|
const title = 'DAxTA';
|
|
77
|
-
const tag = '
|
|
77
|
+
const tag = 'Tested behavior. Trusted API docs.';
|
|
78
78
|
const meta = `v${options.version} · ${options.project}${options.dryRun ? ' · dry-run' : ''}`;
|
|
79
79
|
const inner = 50;
|
|
80
80
|
const pad = (s) => s + ' '.repeat(Math.max(0, inner - s.length));
|
package/dist/cli/uninstall.js
CHANGED
|
@@ -62,7 +62,15 @@ function stripGitignore(cwd, dryRun) {
|
|
|
62
62
|
const gitignorePath = path.join(cwd, '.gitignore');
|
|
63
63
|
if (!(0, fs_1.existsSync)(gitignorePath))
|
|
64
64
|
return [];
|
|
65
|
-
const remove = new Set([
|
|
65
|
+
const remove = new Set([
|
|
66
|
+
'daxta/out/',
|
|
67
|
+
'daxta/',
|
|
68
|
+
'daxta/viewer-store.json',
|
|
69
|
+
'.daxta/out/',
|
|
70
|
+
'.daxta/',
|
|
71
|
+
'.daxta/viewer-store.json',
|
|
72
|
+
'**/.jest.daxta.runtime.json',
|
|
73
|
+
]);
|
|
66
74
|
const before = (0, fs_1.readFileSync)(gitignorePath, 'utf8');
|
|
67
75
|
const lines = before.split(/\r?\n/);
|
|
68
76
|
const kept = lines.filter((line) => !remove.has(line.trim()));
|
|
@@ -232,11 +240,13 @@ async function uninstallDaxta(options = {}) {
|
|
|
232
240
|
(0, fs_1.rmSync)(configPath, { force: true });
|
|
233
241
|
details.push(path.relative(cwd, configPath));
|
|
234
242
|
}
|
|
235
|
-
const
|
|
236
|
-
|
|
237
|
-
if (
|
|
238
|
-
|
|
239
|
-
|
|
243
|
+
for (const dir of ['daxta', '.daxta']) {
|
|
244
|
+
const outDir = path.join(cwd, dir);
|
|
245
|
+
if ((0, fs_1.existsSync)(outDir)) {
|
|
246
|
+
if (!dryRun)
|
|
247
|
+
(0, fs_1.rmSync)(outDir, { recursive: true, force: true });
|
|
248
|
+
details.push(`${dir}/`);
|
|
249
|
+
}
|
|
240
250
|
}
|
|
241
251
|
if (!details.length)
|
|
242
252
|
return 'already gone';
|
package/dist/config.d.ts
CHANGED
|
@@ -19,7 +19,7 @@ export type DaxtaConfig = {
|
|
|
19
19
|
baseUrl?: string;
|
|
20
20
|
/**
|
|
21
21
|
* Multi-base Try-it presets (local / staging / production, …).
|
|
22
|
-
* Seeded into the docs env picker and
|
|
22
|
+
* Seeded into the API docs env picker and `.daxta/viewer-store.json` on first write.
|
|
23
23
|
* Default: `{ local: { baseUrl } }` from `baseUrl`.
|
|
24
24
|
*/
|
|
25
25
|
envPresets?: Record<string, EnvPreset>;
|
|
@@ -42,14 +42,14 @@ export type DaxtaConfig = {
|
|
|
42
42
|
* - status-case → `201 — cyprus payload shape`
|
|
43
43
|
* - status-title-case → `201 — Create Mock Tbs — cyprus payload shape`
|
|
44
44
|
* - full → includes path + POSITIVE CASES + clause
|
|
45
|
-
* Test it() stays `creates mock tbs when cyprus payload shape`; docs take the `when` clause.
|
|
45
|
+
* Test it() stays `creates mock tbs when cyprus payload shape`; API docs take the `when` clause.
|
|
46
46
|
*/
|
|
47
47
|
exampleLabelStyle?: ExampleLabelStyle;
|
|
48
48
|
port?: number;
|
|
49
49
|
fieldsFile?: string;
|
|
50
50
|
docsPath?: string;
|
|
51
51
|
/**
|
|
52
|
-
* Persisted Try-it env/header store (survives rebuild). Default
|
|
52
|
+
* Persisted Try-it env/header store (survives rebuild). Default `.daxta/viewer-store.json`.
|
|
53
53
|
* Served at `{docsPath}/env.json`. Keep out of git if it holds secrets.
|
|
54
54
|
*/
|
|
55
55
|
viewerStoreFile?: string;
|
package/dist/config.js
CHANGED
|
@@ -45,15 +45,15 @@ const DEFAULTS = {
|
|
|
45
45
|
workspace: 'API',
|
|
46
46
|
baseUrl: 'http://localhost:3000',
|
|
47
47
|
controllersRoot: 'src',
|
|
48
|
-
outDir: 'daxta/out',
|
|
48
|
+
outDir: '.daxta/out',
|
|
49
49
|
treeLayout: 'role-resource',
|
|
50
50
|
treeSkipParams: true,
|
|
51
51
|
treePathOverrides: {},
|
|
52
52
|
exampleLabelStyle: 'status-title-case',
|
|
53
53
|
port: 5199,
|
|
54
|
-
fieldsFile: 'daxta
|
|
55
|
-
docsPath: '/docs',
|
|
56
|
-
viewerStoreFile: 'daxta/viewer-store.json',
|
|
54
|
+
fieldsFile: '.daxta/out/fields.json',
|
|
55
|
+
docsPath: '/api-docs',
|
|
56
|
+
viewerStoreFile: '.daxta/viewer-store.json',
|
|
57
57
|
envPresets: {
|
|
58
58
|
local: { baseUrl: 'http://localhost:3000' },
|
|
59
59
|
},
|
package/dist/index.d.ts
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
export { defineConfig, getConfig, resolveConfig, normalizeTreeLayout, type DaxtaConfig, type EnvPreset, type TreeLayout, type ExampleLabelStyle, type SpecInfo } from './config';
|
|
2
|
-
export { buildDaxtaSpec, buildOpenApi, loadHits, type BuildResult, type Scenario } from './build/build-spec';
|
|
2
|
+
export { generateApiDocs, buildDaxtaSpec, buildOpenApi, loadHits, type BuildResult, type Scenario } from './build/build-spec';
|
|
3
3
|
export { rebuildFromDisk, flushAndRebuild, clearPartialMarker, touchPartialMarker } from './build/incremental';
|
|
4
4
|
export { install, flush, clearWorkerHits, getHits, type RecordedHit } from './recorder';
|
|
5
5
|
export { dtoRequired, type FieldLocation } from './fields/dto-fields';
|
|
6
6
|
export { buildFieldsFile, writeFieldsFile, readFieldsFile, type FieldsFile } from './fields/export-fields';
|
|
7
|
-
export { apiDocs, apiDocsHandler, serveApiDocs, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath, type ApiDocsHandler, type ApiDocsOptions, } from './serve';
|
|
7
|
+
export { apiDocs, apiDocsHandler, serveApiDocs, getApiDocs, getApiDocUrl, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath, type ApiDocsHandler, type ApiDocsOptions, } from './serve';
|
|
8
8
|
export { runInteractiveCall, runFileCall, executeCall, type CallValues } from './call';
|
|
9
9
|
export { apiTitle, parseOperationLabel, suggestOperationTitles, suggestOperationTitleResult, formatTestTitle, isValidItCase, suggestItCases, docsScenarioClause, type FieldDoc, type OperationDoc, } from './catalog';
|
|
10
10
|
export { installDaxta, type InstallOptions } from './cli/install';
|
package/dist/index.js
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.installDaxta = exports.docsScenarioClause = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = exports.apiTitle = exports.executeCall = exports.runFileCall = exports.runInteractiveCall = exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.serveApiDocs = exports.apiDocsHandler = exports.apiDocs = exports.readFieldsFile = exports.writeFieldsFile = exports.buildFieldsFile = exports.dtoRequired = exports.getHits = exports.clearWorkerHits = exports.flush = exports.install = exports.touchPartialMarker = exports.clearPartialMarker = exports.flushAndRebuild = exports.rebuildFromDisk = exports.loadHits = exports.buildOpenApi = exports.buildDaxtaSpec = exports.normalizeTreeLayout = exports.resolveConfig = exports.getConfig = exports.defineConfig = void 0;
|
|
3
|
+
exports.installDaxta = exports.docsScenarioClause = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = exports.apiTitle = exports.executeCall = exports.runFileCall = exports.runInteractiveCall = exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.getApiDocUrl = exports.getApiDocs = exports.serveApiDocs = exports.apiDocsHandler = exports.apiDocs = exports.readFieldsFile = exports.writeFieldsFile = exports.buildFieldsFile = exports.dtoRequired = exports.getHits = exports.clearWorkerHits = exports.flush = exports.install = exports.touchPartialMarker = exports.clearPartialMarker = exports.flushAndRebuild = exports.rebuildFromDisk = exports.loadHits = exports.buildOpenApi = exports.buildDaxtaSpec = exports.generateApiDocs = exports.normalizeTreeLayout = exports.resolveConfig = exports.getConfig = exports.defineConfig = void 0;
|
|
4
4
|
var config_1 = require("./config");
|
|
5
5
|
Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return config_1.defineConfig; } });
|
|
6
6
|
Object.defineProperty(exports, "getConfig", { enumerable: true, get: function () { return config_1.getConfig; } });
|
|
7
7
|
Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_1.resolveConfig; } });
|
|
8
8
|
Object.defineProperty(exports, "normalizeTreeLayout", { enumerable: true, get: function () { return config_1.normalizeTreeLayout; } });
|
|
9
9
|
var build_spec_1 = require("./build/build-spec");
|
|
10
|
+
Object.defineProperty(exports, "generateApiDocs", { enumerable: true, get: function () { return build_spec_1.generateApiDocs; } });
|
|
10
11
|
Object.defineProperty(exports, "buildDaxtaSpec", { enumerable: true, get: function () { return build_spec_1.buildDaxtaSpec; } });
|
|
11
12
|
Object.defineProperty(exports, "buildOpenApi", { enumerable: true, get: function () { return build_spec_1.buildOpenApi; } });
|
|
12
13
|
Object.defineProperty(exports, "loadHits", { enumerable: true, get: function () { return build_spec_1.loadHits; } });
|
|
@@ -30,6 +31,8 @@ var serve_1 = require("./serve");
|
|
|
30
31
|
Object.defineProperty(exports, "apiDocs", { enumerable: true, get: function () { return serve_1.apiDocs; } });
|
|
31
32
|
Object.defineProperty(exports, "apiDocsHandler", { enumerable: true, get: function () { return serve_1.apiDocsHandler; } });
|
|
32
33
|
Object.defineProperty(exports, "serveApiDocs", { enumerable: true, get: function () { return serve_1.serveApiDocs; } });
|
|
34
|
+
Object.defineProperty(exports, "getApiDocs", { enumerable: true, get: function () { return serve_1.getApiDocs; } });
|
|
35
|
+
Object.defineProperty(exports, "getApiDocUrl", { enumerable: true, get: function () { return serve_1.getApiDocUrl; } });
|
|
33
36
|
Object.defineProperty(exports, "getDocsBasePath", { enumerable: true, get: function () { return serve_1.getDocsBasePath; } });
|
|
34
37
|
Object.defineProperty(exports, "getHtmlPath", { enumerable: true, get: function () { return serve_1.getHtmlPath; } });
|
|
35
38
|
Object.defineProperty(exports, "getOutDir", { enumerable: true, get: function () { return serve_1.getOutDir; } });
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Optional jest globalTeardown — silent
|
|
3
|
-
*
|
|
2
|
+
* Optional jest globalTeardown — silent generate only.
|
|
3
|
+
* API docs ready is printed by the Jest reporter so we don't own the test process.
|
|
4
4
|
*/
|
|
5
5
|
export default function daxtaGlobalTeardown(): Promise<void>;
|
|
@@ -4,12 +4,12 @@ exports.default = daxtaGlobalTeardown;
|
|
|
4
4
|
const incremental_1 = require("../build/incremental");
|
|
5
5
|
const build_spec_1 = require("../build/build-spec");
|
|
6
6
|
/**
|
|
7
|
-
* Optional jest globalTeardown — silent
|
|
8
|
-
*
|
|
7
|
+
* Optional jest globalTeardown — silent generate only.
|
|
8
|
+
* API docs ready is printed by the Jest reporter so we don't own the test process.
|
|
9
9
|
*/
|
|
10
10
|
async function daxtaGlobalTeardown() {
|
|
11
11
|
try {
|
|
12
|
-
(0, build_spec_1.
|
|
12
|
+
(0, build_spec_1.generateApiDocs)({ silent: true, html: true });
|
|
13
13
|
(0, incremental_1.clearPartialMarker)();
|
|
14
14
|
}
|
|
15
15
|
catch {
|
package/dist/jest/reporter.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Jest reporter — only
|
|
2
|
+
* Jest reporter — only generates API docs when the full run completes.
|
|
3
3
|
* During the run we only record hits (superagent hook + flush); no mid-run rebuilds.
|
|
4
4
|
*/
|
|
5
5
|
declare class DaxtaJestReporter {
|
package/dist/jest/reporter.js
CHANGED
|
@@ -6,15 +6,14 @@ const paths_1 = require("../serve/paths");
|
|
|
6
6
|
function printDocsReady(hits, operations) {
|
|
7
7
|
try {
|
|
8
8
|
(0, config_1.resetConfig)();
|
|
9
|
-
|
|
10
|
-
const
|
|
11
|
-
const url = `${config.baseUrl.replace(/\/$/, '')}${docsBase}`;
|
|
9
|
+
(0, config_1.getConfig)(true);
|
|
10
|
+
const url = (0, paths_1.getApiDocUrl)();
|
|
12
11
|
const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
|
|
13
12
|
const green = (s) => `\x1b[32m${s}\x1b[0m`;
|
|
14
13
|
const dim = (s) => `\x1b[2m${s}\x1b[0m`;
|
|
15
14
|
const bold = (s) => `\x1b[1m${s}\x1b[0m`;
|
|
16
15
|
console.log('');
|
|
17
|
-
console.log(` ${bold('
|
|
16
|
+
console.log(` ${bold('API docs ready')}`);
|
|
18
17
|
console.log(` ${dim('│')} ${green('✔')} ${cyan(url)} ${dim(`(${hits} hits · ${operations} ops)`)}`);
|
|
19
18
|
console.log(` ${dim('│')} ${dim('DAXTA_DOCS=true')} required on app start`);
|
|
20
19
|
console.log('');
|
|
@@ -24,11 +23,11 @@ function printDocsReady(hits, operations) {
|
|
|
24
23
|
console.log('');
|
|
25
24
|
}
|
|
26
25
|
catch {
|
|
27
|
-
console.log(`\nDAxTA docs ready (${hits} hits · ${operations} ops)\n`);
|
|
26
|
+
console.log(`\nDAxTA: API docs ready (${hits} hits · ${operations} ops)\n`);
|
|
28
27
|
}
|
|
29
28
|
}
|
|
30
29
|
/**
|
|
31
|
-
* Jest reporter — only
|
|
30
|
+
* Jest reporter — only generates API docs when the full run completes.
|
|
32
31
|
* During the run we only record hits (superagent hook + flush); no mid-run rebuilds.
|
|
33
32
|
*/
|
|
34
33
|
class DaxtaJestReporter {
|
|
@@ -43,7 +42,7 @@ class DaxtaJestReporter {
|
|
|
43
42
|
printDocsReady(result.hits ?? 0, result.operations ?? 0);
|
|
44
43
|
return;
|
|
45
44
|
}
|
|
46
|
-
const build = (0, build_spec_1.
|
|
45
|
+
const build = (0, build_spec_1.generateApiDocs)({ silent: true, html: true });
|
|
47
46
|
(0, incremental_1.clearPartialMarker)();
|
|
48
47
|
if (!build.skipped)
|
|
49
48
|
printDocsReady(build.hits, build.operations);
|
package/dist/serve/index.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import * as http from 'http';
|
|
2
2
|
export { apiDocs, apiDocsHandler, type ApiDocsHandler, type ApiDocsOptions } from './middleware';
|
|
3
|
-
export { getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath } from './paths';
|
|
4
|
-
/** Standalone docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
|
|
3
|
+
export { getApiDocs, getApiDocUrl, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath } from './paths';
|
|
4
|
+
/** Standalone API docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
|
|
5
5
|
export declare function serveApiDocs(options?: {
|
|
6
6
|
port?: number;
|
|
7
7
|
}): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
|
package/dist/serve/index.js
CHANGED
|
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
-
exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.apiDocsHandler = exports.apiDocs = void 0;
|
|
36
|
+
exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.getApiDocUrl = exports.getApiDocs = exports.apiDocsHandler = exports.apiDocs = void 0;
|
|
37
37
|
exports.serveApiDocs = serveApiDocs;
|
|
38
38
|
const fs_1 = require("fs");
|
|
39
39
|
const http = __importStar(require("http"));
|
|
@@ -47,6 +47,8 @@ var middleware_1 = require("./middleware");
|
|
|
47
47
|
Object.defineProperty(exports, "apiDocs", { enumerable: true, get: function () { return middleware_1.apiDocs; } });
|
|
48
48
|
Object.defineProperty(exports, "apiDocsHandler", { enumerable: true, get: function () { return middleware_1.apiDocsHandler; } });
|
|
49
49
|
var paths_2 = require("./paths");
|
|
50
|
+
Object.defineProperty(exports, "getApiDocs", { enumerable: true, get: function () { return paths_2.getApiDocs; } });
|
|
51
|
+
Object.defineProperty(exports, "getApiDocUrl", { enumerable: true, get: function () { return paths_2.getApiDocUrl; } });
|
|
50
52
|
Object.defineProperty(exports, "getDocsBasePath", { enumerable: true, get: function () { return paths_2.getDocsBasePath; } });
|
|
51
53
|
Object.defineProperty(exports, "getHtmlPath", { enumerable: true, get: function () { return paths_2.getHtmlPath; } });
|
|
52
54
|
Object.defineProperty(exports, "getOutDir", { enumerable: true, get: function () { return paths_2.getOutDir; } });
|
|
@@ -61,7 +63,7 @@ async function readBody(req) {
|
|
|
61
63
|
chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
|
|
62
64
|
return Buffer.concat(chunks);
|
|
63
65
|
}
|
|
64
|
-
/** Standalone docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
|
|
66
|
+
/** Standalone API docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
|
|
65
67
|
function serveApiDocs(options = {}) {
|
|
66
68
|
const config = (0, config_1.getConfig)();
|
|
67
69
|
const port = options.port ?? Number(process.env.DAXTA_DOCS_PORT || process.env.OPENAPI_DOCS_PORT || config.port);
|
|
@@ -138,7 +140,7 @@ function serveApiDocs(options = {}) {
|
|
|
138
140
|
if (url.pathname === '/openapi.json' || url.pathname === `${docsBase}/openapi.json`) {
|
|
139
141
|
const body = (0, spec_utils_1.readStrippedOpenApiJson)();
|
|
140
142
|
if (!body) {
|
|
141
|
-
send(res, 404, 'openapi.json not found. Run `daxta
|
|
143
|
+
send(res, 404, 'openapi.json not found. Run `daxta generate` first.');
|
|
142
144
|
return;
|
|
143
145
|
}
|
|
144
146
|
send(res, 200, body, {
|
|
@@ -151,9 +153,9 @@ function serveApiDocs(options = {}) {
|
|
|
151
153
|
send(res, 404, 'Not found');
|
|
152
154
|
});
|
|
153
155
|
server.listen(port, '127.0.0.1', () => {
|
|
154
|
-
console.log(`
|
|
155
|
-
console.log(`
|
|
156
|
-
console.log(`
|
|
156
|
+
console.log(`API docs: http://127.0.0.1:${port}${docsBase}`);
|
|
157
|
+
console.log(`API spec: http://127.0.0.1:${port}${docsBase}/openapi.json`);
|
|
158
|
+
console.log(`API docs env: http://127.0.0.1:${port}${docsBase}/env.json`);
|
|
157
159
|
});
|
|
158
160
|
return server;
|
|
159
161
|
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export type ApiDocsOptions = {
|
|
2
|
-
/** URL prefix for the viewer. Default from config (`docsPath`) or `/docs`. */
|
|
2
|
+
/** URL prefix for the API docs viewer. Default from config (`docsPath`) or `/api-docs`. */
|
|
3
3
|
basePath?: string;
|
|
4
4
|
};
|
|
5
5
|
type LooseRequest = {
|
|
@@ -22,16 +22,16 @@ type LooseResponse = {
|
|
|
22
22
|
};
|
|
23
23
|
export type ApiDocsHandler = (req: LooseRequest, res: LooseResponse, next: (error?: unknown) => void) => void | Promise<void>;
|
|
24
24
|
/**
|
|
25
|
-
* Express / Nest handler that serves
|
|
25
|
+
* Express / Nest handler that serves generated API docs under `/api-docs`
|
|
26
26
|
* (or `basePath`), Try-it proxy at `/__proxy`, and env store at `{base}/env.json`.
|
|
27
27
|
*/
|
|
28
28
|
export declare function apiDocsHandler(options?: ApiDocsOptions): ApiDocsHandler;
|
|
29
29
|
/**
|
|
30
|
-
*
|
|
30
|
+
* Mount generated API docs on a Nest / Express app (`app.use(...)`).
|
|
31
31
|
*
|
|
32
32
|
* Requires `DAXTA_DOCS` in the environment:
|
|
33
33
|
* - missing / empty → throws (app must set it explicitly)
|
|
34
|
-
* - `true` | `1` | `yes` | `on` → serve
|
|
34
|
+
* - `true` | `1` | `yes` | `on` → serve API docs
|
|
35
35
|
* - `false` | `0` | `no` | `off` → no-op
|
|
36
36
|
*/
|
|
37
37
|
export declare function apiDocs(app: {
|
package/dist/serve/middleware.js
CHANGED
|
@@ -96,11 +96,11 @@ async function readRequestJson(req) {
|
|
|
96
96
|
}
|
|
97
97
|
}
|
|
98
98
|
/**
|
|
99
|
-
* Express / Nest handler that serves
|
|
99
|
+
* Express / Nest handler that serves generated API docs under `/api-docs`
|
|
100
100
|
* (or `basePath`), Try-it proxy at `/__proxy`, and env store at `{base}/env.json`.
|
|
101
101
|
*/
|
|
102
102
|
function apiDocsHandler(options = {}) {
|
|
103
|
-
const basePath = (options.basePath ?? (0, paths_1.getDocsBasePath)()).replace(/\/$/, '') || '/docs';
|
|
103
|
+
const basePath = (options.basePath ?? (0, paths_1.getDocsBasePath)()).replace(/\/$/, '') || '/api-docs';
|
|
104
104
|
return async (req, res, next) => {
|
|
105
105
|
const method = (req.method || 'GET').toUpperCase();
|
|
106
106
|
const pathname = requestPathname(req);
|
|
@@ -163,7 +163,7 @@ function apiDocsHandler(options = {}) {
|
|
|
163
163
|
if (isDocsSpec) {
|
|
164
164
|
const body = (0, spec_utils_1.readStrippedOpenApiJson)();
|
|
165
165
|
if (!body) {
|
|
166
|
-
write(res, 404, 'openapi.json not found. Run `daxta
|
|
166
|
+
write(res, 404, 'openapi.json not found. Run `daxta generate` first.', { 'content-type': 'text/plain; charset=utf-8' });
|
|
167
167
|
return;
|
|
168
168
|
}
|
|
169
169
|
write(res, 200, body, {
|
|
@@ -190,17 +190,17 @@ function apiDocsHandler(options = {}) {
|
|
|
190
190
|
};
|
|
191
191
|
}
|
|
192
192
|
/**
|
|
193
|
-
*
|
|
193
|
+
* Mount generated API docs on a Nest / Express app (`app.use(...)`).
|
|
194
194
|
*
|
|
195
195
|
* Requires `DAXTA_DOCS` in the environment:
|
|
196
196
|
* - missing / empty → throws (app must set it explicitly)
|
|
197
|
-
* - `true` | `1` | `yes` | `on` → serve
|
|
197
|
+
* - `true` | `1` | `yes` | `on` → serve API docs
|
|
198
198
|
* - `false` | `0` | `no` | `off` → no-op
|
|
199
199
|
*/
|
|
200
200
|
function apiDocs(app, options = {}) {
|
|
201
201
|
const raw = process.env.DAXTA_DOCS;
|
|
202
202
|
if (raw == null || String(raw).trim() === '') {
|
|
203
|
-
throw new Error('DAxTA: DAXTA_DOCS is not set. Set DAXTA_DOCS=true to enable
|
|
203
|
+
throw new Error('DAxTA: DAXTA_DOCS is not set. Set DAXTA_DOCS=true to enable API docs, or DAXTA_DOCS=false to disable.');
|
|
204
204
|
}
|
|
205
205
|
const normalized = String(raw).trim().toLowerCase();
|
|
206
206
|
const enabled = ['1', 'true', 'yes', 'on'].includes(normalized);
|
package/dist/serve/paths.d.ts
CHANGED
|
@@ -9,3 +9,11 @@ export declare function getEmptyViewerAssetPath(): string;
|
|
|
9
9
|
export declare function readEmptyDocsHtml(): Buffer;
|
|
10
10
|
export declare function getFaviconAssetPath(): string;
|
|
11
11
|
export declare function getDocsBasePath(): string;
|
|
12
|
+
/** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/api-docs`). */
|
|
13
|
+
export declare function getApiDocUrl(): string;
|
|
14
|
+
/** Paths and URL for the generated API docs artifact. */
|
|
15
|
+
export declare function getApiDocs(): {
|
|
16
|
+
url: string;
|
|
17
|
+
specPath: string;
|
|
18
|
+
htmlPath: string;
|
|
19
|
+
};
|
package/dist/serve/paths.js
CHANGED
|
@@ -43,6 +43,8 @@ exports.getEmptyViewerAssetPath = getEmptyViewerAssetPath;
|
|
|
43
43
|
exports.readEmptyDocsHtml = readEmptyDocsHtml;
|
|
44
44
|
exports.getFaviconAssetPath = getFaviconAssetPath;
|
|
45
45
|
exports.getDocsBasePath = getDocsBasePath;
|
|
46
|
+
exports.getApiDocUrl = getApiDocUrl;
|
|
47
|
+
exports.getApiDocs = getApiDocs;
|
|
46
48
|
const fs_1 = require("fs");
|
|
47
49
|
const path = __importStar(require("path"));
|
|
48
50
|
const config_1 = require("../config");
|
|
@@ -68,9 +70,9 @@ function getViewerAssetPath() {
|
|
|
68
70
|
function getEmptyViewerAssetPath() {
|
|
69
71
|
return path.join(__dirname, '..', '..', 'assets', 'empty.html');
|
|
70
72
|
}
|
|
71
|
-
const EMPTY_DOCS_FALLBACK = `<!doctype html><html lang="en"><head><meta charset="utf-8"/><title>
|
|
73
|
+
const EMPTY_DOCS_FALLBACK = `<!doctype html><html lang="en"><head><meta charset="utf-8"/><title>API Documentation</title></head><body style="font:13px/1.45 system-ui;background:#fafafa;color:#111;margin:0;padding:48px 24px">
|
|
72
74
|
<p style="font:600 10px/1 ui-monospace,monospace;letter-spacing:.08em;text-transform:uppercase;color:#666">Waiting</p>
|
|
73
|
-
<h1 style="font-size:22px;letter-spacing:-.04em">No documentation yet</h1>
|
|
75
|
+
<h1 style="font-size:22px;letter-spacing:-.04em">No API documentation yet</h1>
|
|
74
76
|
<p>Run your integration tests, then refresh this page.</p>
|
|
75
77
|
</body></html>`;
|
|
76
78
|
function readEmptyDocsHtml() {
|
|
@@ -86,6 +88,19 @@ function getFaviconAssetPath() {
|
|
|
86
88
|
return path.join(__dirname, '..', '..', 'assets', 'favicon.png');
|
|
87
89
|
}
|
|
88
90
|
function getDocsBasePath() {
|
|
89
|
-
const configured = (0, config_1.getConfig)().docsPath ?? '/docs';
|
|
90
|
-
return configured.startsWith('/') ? configured.replace(/\/$/, '') || '/docs' : `/${configured}`.replace(/\/$/, '');
|
|
91
|
+
const configured = (0, config_1.getConfig)().docsPath ?? '/api-docs';
|
|
92
|
+
return configured.startsWith('/') ? configured.replace(/\/$/, '') || '/api-docs' : `/${configured}`.replace(/\/$/, '');
|
|
93
|
+
}
|
|
94
|
+
/** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/api-docs`). */
|
|
95
|
+
function getApiDocUrl() {
|
|
96
|
+
const config = (0, config_1.getConfig)();
|
|
97
|
+
return `${String(config.baseUrl || '').replace(/\/$/, '')}${getDocsBasePath()}`;
|
|
98
|
+
}
|
|
99
|
+
/** Paths and URL for the generated API docs artifact. */
|
|
100
|
+
function getApiDocs() {
|
|
101
|
+
return {
|
|
102
|
+
url: getApiDocUrl(),
|
|
103
|
+
specPath: getSpecJsonPath(),
|
|
104
|
+
htmlPath: getHtmlPath(),
|
|
105
|
+
};
|
|
91
106
|
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@t0.labs/daxta",
|
|
3
|
-
"version": "0.5.
|
|
4
|
-
"description": "DAxTA
|
|
3
|
+
"version": "0.5.1",
|
|
4
|
+
"description": "DAxTA — Tested behavior. Trusted API docs. Generate API documentation from observed test execution.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|