@t0.labs/daxta 0.4.24 → 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 +6 -5
- package/assets/example.html +237 -246
- package/assets/favicon.png +0 -0
- package/assets/favicon.svg +16 -0
- package/assets/logo.png +0 -0
- package/assets/viewer.html +164 -113
- package/dist/build/build-spec.d.ts +3 -1
- package/dist/build/build-spec.js +11 -6
- 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 +22 -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,8 @@
|
|
|
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
|
+
<link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+CiAgPHN0eWxlPgogICAgLmJnIHsgZmlsbDogI2ZmZmZmZjsgfQogICAgLmZnIHsgZmlsbDogIzExMTExMTsgfQogICAgLnJpbmcgeyBmaWxsOiBub25lOyBzdHJva2U6ICMxMTExMTE7IHN0cm9rZS13aWR0aDogMS4yNTsgfQogICAgQG1lZGlhIChwcmVmZXJzLWNvbG9yLXNjaGVtZTogZGFyaykgewogICAgICAuYmcgeyBmaWxsOiAjMTExMTExOyB9CiAgICAgIC5mZyB7IGZpbGw6ICNmZmZmZmY7IH0KICAgICAgLnJpbmcgeyBzdHJva2U6ICNmZmZmZmY7IH0KICAgIH0KICA8L3N0eWxlPgogIDxyZWN0IGNsYXNzPSJiZyIgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIvPgogIDxyZWN0IGNsYXNzPSJyaW5nIiB4PSIwLjYiIHk9IjAuNiIgd2lkdGg9IjMwLjgiIGhlaWdodD0iMzAuOCIgcng9IjYuNCIvPgogIDxwYXRoIGNsYXNzPSJmZyIgZD0iTTQuMiA1LjIgMTQuMiA4Ljh2NC4yQTQuMiA0LjIgMCAwIDEgMTQuMiAyMS40djRMNC4yIDI2LjhaIi8+CiAgPHBhdGggY2xhc3M9ImZnIiBkPSJNMjcuOCA1LjIgMTcuOCA4Ljh2NC4yQTQuMiA0LjIgMCAwIDAgMTcuOCAyMS40djRMMjcuOCAyNi44WiIvPgo8L3N2Zz4K" />
|
|
7
8
|
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
|
8
9
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
|
9
10
|
<link href="https://fonts.googleapis.com/css2?family=Geist+Mono:wght@400;500;600&family=Geist:wght@400;500;600&display=swap" rel="stylesheet" />
|
|
@@ -133,23 +134,23 @@
|
|
|
133
134
|
</head>
|
|
134
135
|
<body>
|
|
135
136
|
<header class="topnav">
|
|
136
|
-
<span class="nav-meta">/docs</span>
|
|
137
|
+
<span class="nav-meta">/api-docs</span>
|
|
137
138
|
</header>
|
|
138
139
|
<main class="stage">
|
|
139
140
|
<div class="panel">
|
|
140
141
|
<p class="kicker">Waiting</p>
|
|
141
|
-
<h1>No documentation yet</h1>
|
|
142
|
+
<h1>No API documentation yet</h1>
|
|
142
143
|
<p>This page publishes when API traffic has been recorded. Run your integration tests, then refresh.</p>
|
|
143
144
|
<ol class="steps">
|
|
144
145
|
<li><span class="n">1</span><span>Run the integration suite that hits your API.</span></li>
|
|
145
|
-
<li><span class="n">2</span><span>
|
|
146
|
+
<li><span class="n">2</span><span>DAxTA writes API docs from those requests and responses.</span></li>
|
|
146
147
|
<li><span class="n">3</span><span>Reload this page to open the workbench.</span></li>
|
|
147
148
|
</ol>
|
|
148
149
|
<pre class="cmd">pnpm run test:integration</pre>
|
|
149
150
|
<div class="actions">
|
|
150
151
|
<button class="btn primary" type="button" id="reload">Refresh</button>
|
|
151
152
|
</div>
|
|
152
|
-
<div class="foot">Generated by
|
|
153
|
+
<div class="foot">Generated by DAxTA</div>
|
|
153
154
|
</div>
|
|
154
155
|
</main>
|
|
155
156
|
<script>
|