swagger-digest 0.3.0 → 0.3.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 +210 -135
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,101 +1,141 @@
|
|
|
1
1
|
# swagger-digest
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/swagger-digest)
|
|
4
|
+
[](https://github.com/VladLegkowski/swagger-digest)
|
|
5
|
+
[](https://www.npmjs.com/package/swagger-digest)
|
|
6
|
+
[](https://modelcontextprotocol.io)
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
**An API context engine for AI coding agents.** Turn large Swagger/OpenAPI specifications into compact, structured, searchable API context — as Markdown digests or through an on-demand MCP server.
|
|
6
9
|
|
|
7
|
-
|
|
8
|
-
npx swagger-digest
|
|
9
|
-
```
|
|
10
|
+
A 600-operation spec like Stripe's is ~2M tokens of raw JSON — several times most models' context windows, and mostly noise even when it fits. swagger-digest reduces it to ~560k tokens of structured Markdown (benchmark below), and its MCP server lets your agent pull in only the endpoints and schemas it needs, when it needs them.
|
|
10
11
|
|
|
11
|
-
The
|
|
12
|
+
## The problem
|
|
12
13
|
|
|
13
|
-
|
|
14
|
+
- Real specifications contain hundreds of endpoints and thousands of lines of JSON/YAML.
|
|
15
|
+
- Pasting a raw spec into an AI coding agent burns context on boilerplate — descriptions repeated per operation, example payloads, schema trees.
|
|
16
|
+
- Finding the endpoints relevant to your task — and understanding their parameters and response shapes — means manually wading through the contract.
|
|
17
|
+
- Agents generating frontend code need accurate API contracts. Guessing field names from partial context produces broken integrations.
|
|
14
18
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
swagger-digest solves this at two levels: a **digest** (compact, complete, token-budgeted Markdown) and an **MCP server** (on-demand API context for agents).
|
|
20
|
+
|
|
21
|
+
## Two ways to use it
|
|
22
|
+
|
|
23
|
+
### Option 1: MCP server — recommended for AI coding agents
|
|
24
|
+
|
|
25
|
+
Run it as an [MCP](https://modelcontextprotocol.io) server and your agent explores APIs on its own: it calls the `swagger_digest` tool with a Swagger UI page or spec URL and receives a compact digest directly in its context — discovery, filtering and token budgets handled for it.
|
|
26
|
+
|
|
27
|
+
- **On-demand:** the agent fetches API context only when the task needs it.
|
|
28
|
+
- **Scoped:** filter to specific tags or paths so only relevant operations enter context.
|
|
29
|
+
- **Discovery built in:** point it at a Swagger UI page — it finds the spec automatically (initializer scripts, multi-spec dropdowns, common spec paths).
|
|
30
|
+
- **Ideal for ongoing development work**, where the agent revisits the same API repeatedly without you re-pasting documentation.
|
|
21
31
|
|
|
22
|
-
|
|
32
|
+
Install in your MCP client (stdio transport; the client spawns the process):
|
|
23
33
|
|
|
24
34
|
```bash
|
|
25
|
-
|
|
35
|
+
# OpenCode
|
|
36
|
+
opencode mcp add swagger-digest -- npx -y swagger-digest-mcp
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
// JSON-configured clients (Claude Desktop, Cursor, …)
|
|
41
|
+
{
|
|
42
|
+
"mcpServers": {
|
|
43
|
+
"swagger-digest": {
|
|
44
|
+
"command": ["npx", "-y", "swagger-digest-mcp"]
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
26
48
|
```
|
|
27
49
|
|
|
28
|
-
|
|
50
|
+
Tool arguments and environment variables are documented in [MCP configuration](#mcp-configuration).
|
|
51
|
+
|
|
52
|
+
### Option 2: Markdown digest
|
|
53
|
+
|
|
54
|
+
Generate a compact Markdown reference from any Swagger UI page or OpenAPI/Swagger spec — for documentation, sharing, or feeding API context into agents that don't use MCP.
|
|
29
55
|
|
|
30
56
|
```bash
|
|
31
|
-
|
|
32
|
-
|
|
57
|
+
# Interactive
|
|
58
|
+
npx swagger-digest
|
|
59
|
+
|
|
60
|
+
# Direct: fetch, digest, save
|
|
61
|
+
npx swagger-digest --url https://petstore.swagger.io/ --out-dir ./docs
|
|
62
|
+
|
|
63
|
+
# To stdout (pipes stay clean; progress goes to stderr)
|
|
64
|
+
npx swagger-digest --url https://petstore.swagger.io/ --stdout | pbcopy
|
|
65
|
+
|
|
66
|
+
# Keep only the operations you need
|
|
67
|
+
npx swagger-digest --url https://api.example.com/openapi.json \
|
|
68
|
+
--include-tag Subscriptions --path-prefix /v1/ --out-dir ./docs
|
|
33
69
|
```
|
|
34
70
|
|
|
35
|
-
|
|
71
|
+
Output is a structured Markdown document: endpoint index, per-tag operation details (auth, parameters, request/response bodies, examples), and TypeScript-like data type declarations. Save it next to your code, paste it into a PR, or drop it into your agent's context manually.
|
|
36
72
|
|
|
37
|
-
|
|
73
|
+
## Quick start
|
|
38
74
|
|
|
39
75
|
```bash
|
|
40
|
-
|
|
41
|
-
npx swagger-digest --url https://
|
|
76
|
+
# 1. Generate a digest from a public API (interactive prompts, saved to ~/Downloads)
|
|
77
|
+
npx swagger-digest --url https://petstore.swagger.io/
|
|
78
|
+
|
|
79
|
+
# 2. Or generate to stdout
|
|
80
|
+
npx swagger-digest --url https://petstore.swagger.io/ --stdout > petstore-digest.md
|
|
81
|
+
|
|
82
|
+
# 3. Register the MCP server (OpenCode example)
|
|
83
|
+
opencode mcp add swagger-digest -- npx -y swagger-digest-mcp
|
|
42
84
|
```
|
|
43
85
|
|
|
44
|
-
|
|
86
|
+
Requires Node.js 20+. Run `npx swagger-digest --help` for all options.
|
|
45
87
|
|
|
46
|
-
|
|
88
|
+
## Real-world example: building a subscriptions page
|
|
47
89
|
|
|
48
|
-
|
|
90
|
+
A React/TypeScript developer asks their AI coding agent:
|
|
49
91
|
|
|
50
|
-
|
|
92
|
+
> "Implement a subscription management page against our billing API — docs are at https://api.example.com/swagger-ui"
|
|
51
93
|
|
|
52
|
-
|
|
53
|
-
npx swagger-digest-mcp
|
|
54
|
-
```
|
|
94
|
+
**Without swagger-digest**, the agent either guesses the API contract or you paste thousands of lines of raw JSON into the conversation.
|
|
55
95
|
|
|
56
|
-
|
|
96
|
+
**With the MCP server**, the agent calls the tool itself:
|
|
57
97
|
|
|
58
98
|
```json
|
|
59
99
|
{
|
|
60
|
-
"
|
|
61
|
-
|
|
62
|
-
"command": ["npx", "-y", "swagger-digest-mcp"]
|
|
63
|
-
}
|
|
64
|
-
}
|
|
100
|
+
"url": "https://api.example.com/swagger-ui",
|
|
101
|
+
"include_tags": ["Subscriptions"]
|
|
65
102
|
}
|
|
66
103
|
```
|
|
67
104
|
|
|
68
|
-
|
|
105
|
+
and receives only the relevant slice — in this illustrative excerpt of digest output:
|
|
106
|
+
|
|
107
|
+
```markdown
|
|
108
|
+
#### `GET /v1/subscriptions/{id}`
|
|
69
109
|
|
|
70
|
-
|
|
71
|
-
| --------------- | ---------------- | -------------------------------------------------------------------------- |
|
|
72
|
-
| `url` | string, required | Swagger UI page URL or direct OpenAPI spec URL |
|
|
73
|
-
| `spec_url` | string, optional | Explicit spec URL; overrides discovery from the page |
|
|
74
|
-
| `headers` | object, optional | Request headers (e.g. `Authorization`); sent only to the origin of `url` |
|
|
75
|
-
| `include_tags` | string[] | Keep only operations with these tags |
|
|
76
|
-
| `exclude_tags` | string[] | Drop operations with these tags |
|
|
77
|
-
| `path_prefix` | string | Keep only paths starting with this prefix |
|
|
78
|
-
| `max_tokens` | number | Trim the digest to an approximate token budget |
|
|
79
|
-
| `write_to_file` | object, optional | `{ directory, filename }` — save the digest instead of returning it inline |
|
|
110
|
+
**Authentication:** Bearer
|
|
80
111
|
|
|
81
|
-
|
|
112
|
+
**Parameters**
|
|
82
113
|
|
|
83
|
-
|
|
114
|
+
- `id` (`path`, required) · `string` — Subscription identifier.
|
|
115
|
+
- `expand` (`query`, optional) · `string[]` — Fields to expand.
|
|
84
116
|
|
|
85
|
-
|
|
86
|
-
- `SWAGGER_DIGEST_ALLOW_PRIVATE=1` — opt out of the private-network guard (see below).
|
|
117
|
+
**Responses**
|
|
87
118
|
|
|
88
|
-
|
|
119
|
+
- **200 OK** — `Subscription` (application/json)
|
|
89
120
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
121
|
+
## Data types
|
|
122
|
+
|
|
123
|
+
export interface Subscription {
|
|
124
|
+
id?: string;
|
|
125
|
+
status?: "active" | "canceled" | "past_due";
|
|
126
|
+
current_period_end?: number;
|
|
127
|
+
items?: SubscriptionItems;
|
|
128
|
+
[key: string]: unknown;
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
From there the agent can: confirm the exact path, method and required parameters; read the `Subscription` schema and its referenced types; generate TypeScript types that match the contract; and implement the page without guessing. If the digest is too large, the agent re-calls with `path_prefix` or `max_tokens` to narrow it further.
|
|
93
133
|
|
|
94
134
|
## Benchmarks
|
|
95
135
|
|
|
96
136
|
Ten public APIs, digest vs. raw spec JSON in an LLM context, ground truth from the parsed raw specs. Run in November 2026 against swagger-digest 0.2.0; token counts are heuristic estimates, not tokenizer-exact.
|
|
97
137
|
|
|
98
|
-
**7/10 wins · 100% operation coverage on every digest produced · 1.6–3.7× lighter · 1 call vs 1–5**
|
|
138
|
+
**7/10 wins · 100% operation coverage on every digest produced · 1.6–3.7× lighter · 1 tool call vs 1–5 fetch/guess attempts**
|
|
99
139
|
|
|
100
140
|
| Spec | Ops | Raw tokens | Digest tokens | Compression | Op coverage | Winner |
|
|
101
141
|
| ------------------- | ----- | ---------------------- | ----------------------- | ----------- | ----------- | ------- |
|
|
@@ -112,6 +152,8 @@ Ten public APIs, digest vs. raw spec JSON in an LLM context, ground truth from t
|
|
|
112
152
|
|
|
113
153
|
> For its target use case — understanding an API in an LLM context — the digest wins on the spec class that actually matters (up to ~600 operations): 100% endpoint coverage, never truncated, one call, and 1.6–3.7× lighter. The bigger the spec, the bigger the win.
|
|
114
154
|
|
|
155
|
+
**Why token efficiency matters:** an agent's context window is shared between your codebase, the conversation, and every tool result. A raw spec that consumes 500k tokens crowds out everything else; the same API as a 150k-token digest leaves room to work — and smaller digests mean faster, cheaper, more focused generations.
|
|
156
|
+
|
|
115
157
|
\* Raw's three "wins" carry heavy caveats: the Petstore UI-page case needed brute-forced candidate URLs (the digest's discovery has since been fixed for that class of pages); GitHub's 3.55M-token raw spec would truncate in any model's context anyway; and the Kubernetes expansion is now prevented by the default token cap described below.
|
|
116
158
|
|
|
117
159
|
### Known failure modes (and their mitigations)
|
|
@@ -122,134 +164,174 @@ Ten public APIs, digest vs. raw spec JSON in an LLM context, ground truth from t
|
|
|
122
164
|
| Mega-specs (Kubernetes-class, ≥1M tokens) | Digest can _expand_ past raw size — descriptions inlined per operation | **Default in 0.3.0**: automatic 250k-token cap (opt out with `--no-auto-trim` / `auto_trim: false`). Explicit `max_tokens` always wins |
|
|
123
165
|
| Huge fetches (14 MB GitHub spec) | Fetch fails at the 10 MB response cap | Use a filtered direct spec URL |
|
|
124
166
|
|
|
125
|
-
|
|
167
|
+
Not every specification benefits: very large kitchen-sink specs are where compression can invert — handled by the default cap, but worth knowing.
|
|
126
168
|
|
|
127
|
-
|
|
169
|
+
## Feature overview
|
|
128
170
|
|
|
129
|
-
|
|
130
|
-
# Keep only operations tagged "Payments", plus everything under /invoices
|
|
131
|
-
npx swagger-digest --url https://api.example.com/openapi.json \
|
|
132
|
-
--include-tag Payments --path-prefix /payments/ --out-dir ./docs
|
|
171
|
+
**Ingestion and discovery**
|
|
133
172
|
|
|
134
|
-
|
|
135
|
-
|
|
173
|
+
- Fetches direct OpenAPI JSON/YAML URLs and Swagger UI pages (OpenAPI 2.0, 3.0, 3.1).
|
|
174
|
+
- Multi-strategy discovery: direct spec URL → page script configuration (`url:`, `urls:` dropdown, inline `spec:`, dynamically computed initializer URLs) → common spec paths (`/v3/api-docs`, `/swagger.json`, …) → optional headless-browser fallback.
|
|
175
|
+
- Multi-spec Swagger UI dropdowns: probes candidates in order, uses the first that parses, names the pick.
|
|
176
|
+
- External `$ref` bundling: references to other HTTP(S) documents are fetched and inlined under namespaced names (one level deep, at most 5 documents).
|
|
136
177
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
178
|
+
**Markdown generation**
|
|
179
|
+
|
|
180
|
+
- Endpoint index plus per-tag operation details: auth requirements, path/query/header parameters, request bodies, success/error responses, examples.
|
|
181
|
+
- TypeScript-like type declarations for reachable schemas; `allOf`/`oneOf`/`anyOf`, enums, arrays, nullable fields, `additionalProperties` get compact representations.
|
|
182
|
+
- Unknown schema constructs render as `unknown` instead of failing the digest.
|
|
183
|
+
- Synthetic examples generated from schemas when none are declared, clearly marked as illustrative.
|
|
140
184
|
|
|
141
|
-
|
|
185
|
+
**MCP server**
|
|
142
186
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
4. Keep only the Quick index entries (no endpoint detail, no data types).
|
|
187
|
+
- Single `swagger_digest` tool over stdio; digest returned inline in the tool result with metadata (retrieval method, operation/model counts, token estimate), or written to a file.
|
|
188
|
+
- Same discovery and filtering pipeline as the CLI; optional Playwright fallback disabled.
|
|
189
|
+
- Private-network (SSRF) guard on by default, because URLs come from the model.
|
|
147
190
|
|
|
148
|
-
|
|
191
|
+
**Filtering and token management**
|
|
149
192
|
|
|
150
|
-
|
|
193
|
+
- Filter by tags (`include_tags`/`exclude_tags`) and path prefix, before rendering.
|
|
194
|
+
- `max_tokens` budget with deterministic trim order; `## Trimmed` note records exactly what was removed.
|
|
195
|
+
- Automatic 250,000-token default cap for unbounded digests.
|
|
151
196
|
|
|
152
|
-
|
|
197
|
+
**Authentication and remote access**
|
|
153
198
|
|
|
154
|
-
|
|
199
|
+
- Origin-scoped custom headers and cookies: sent only to the origin you supply, never logged, never written to the digest.
|
|
200
|
+
- `SWAGGER_DIGEST_HEADER` environment variable for secrets outside the command line.
|
|
201
|
+
- Hardened fetching: response size cap (10 MB), redirect limit (5), timeouts, optional private-network blocking.
|
|
155
202
|
|
|
156
|
-
|
|
203
|
+
## Configuration and advanced usage
|
|
157
204
|
|
|
158
|
-
|
|
159
|
-
2. Fetch the Swagger UI page and inspect script configuration for `url: "..."` or an inline `spec: { ... }` object, plus any spec-like URLs embedded in same-origin initializer scripts (covers initializers that compute the spec URL dynamically).
|
|
160
|
-
3. Try common spec endpoints on the same origin: `/v3/api-docs`, `/swagger/v1/swagger.json`, `/swagger.json`, `/openapi.json`, and `/api-docs`.
|
|
161
|
-
4. Optionally launch a headless Chromium browser and read the parsed specification from Swagger UI's in-memory state.
|
|
205
|
+
### CLI reference
|
|
162
206
|
|
|
163
|
-
|
|
207
|
+
| Option | Description |
|
|
208
|
+
| ------------------------------ | --------------------------------------------------------- |
|
|
209
|
+
| `-u, --url <url>` | Swagger UI page URL or direct OpenAPI spec URL |
|
|
210
|
+
| `-d, --out-dir <directory>` | Destination directory for the digest file |
|
|
211
|
+
| `-f, --filename <filename>` | Output filename (defaults to `<api-title>-digest.md`) |
|
|
212
|
+
| `--stdout` | Print to stdout instead of writing a file |
|
|
213
|
+
| `--spec <url>` | Explicit spec URL; overrides all discovery |
|
|
214
|
+
| `--include-tag <tag>` | Keep only operations with this tag (repeatable) |
|
|
215
|
+
| `--exclude-tag <tag>` | Drop operations with this tag (repeatable) |
|
|
216
|
+
| `--path-prefix <prefix>` | Keep only operations whose path starts with this prefix |
|
|
217
|
+
| `--max-tokens <n>` | Trim the digest until the token estimate fits this budget |
|
|
218
|
+
| `--no-auto-trim` | Disable the automatic 250,000-token default cap |
|
|
219
|
+
| `--max-bytes <bytes>` | Maximum response size (default 10,000,000) |
|
|
220
|
+
| `-H, --header <"Name: value">` | Custom request header, repeatable; origin-scoped |
|
|
221
|
+
| `--cookie <string>` | Convenience for a Cookie header; origin-scoped |
|
|
222
|
+
| `--no-browser` | Disable the optional Playwright fallback |
|
|
223
|
+
|
|
224
|
+
### MCP configuration
|
|
225
|
+
|
|
226
|
+
Register the server (stdio transport):
|
|
164
227
|
|
|
165
228
|
```bash
|
|
166
|
-
|
|
167
|
-
npx
|
|
229
|
+
# OpenCode
|
|
230
|
+
opencode mcp add swagger-digest -- npx -y swagger-digest-mcp
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
```json
|
|
234
|
+
// JSON-configured clients
|
|
235
|
+
{
|
|
236
|
+
"mcpServers": {
|
|
237
|
+
"swagger-digest": {
|
|
238
|
+
"command": ["npx", "-y", "swagger-digest-mcp"]
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
}
|
|
168
242
|
```
|
|
169
243
|
|
|
170
|
-
|
|
244
|
+
The `swagger_digest` tool:
|
|
171
245
|
|
|
172
|
-
|
|
246
|
+
| Argument | Type | Description |
|
|
247
|
+
| --------------- | ---------------- | ------------------------------------------------------------ |
|
|
248
|
+
| `url` | string, required | Swagger UI page URL or direct OpenAPI spec URL |
|
|
249
|
+
| `spec_url` | string | Explicit spec URL; overrides discovery |
|
|
250
|
+
| `headers` | object | Request headers; sent only to the origin of `url` |
|
|
251
|
+
| `include_tags` | string[] | Keep only operations with these tags |
|
|
252
|
+
| `exclude_tags` | string[] | Drop operations with these tags |
|
|
253
|
+
| `path_prefix` | string | Keep only paths starting with this prefix |
|
|
254
|
+
| `max_tokens` | number | Trim the digest to an approximate token budget |
|
|
255
|
+
| `auto_trim` | boolean | Default-cap digests without `max_tokens` (default true) |
|
|
256
|
+
| `write_to_file` | object | `{ directory, filename }` — save instead of returning inline |
|
|
173
257
|
|
|
174
|
-
|
|
258
|
+
MCP environment variables:
|
|
175
259
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
--out-dir ./docs
|
|
181
|
-
```
|
|
260
|
+
- `SWAGGER_DIGEST_HEADER` — newline-separated `Name: value` pairs, merged with (and overridden by) the call's `headers`. Keeps secrets out of the conversation.
|
|
261
|
+
- `SWAGGER_DIGEST_ALLOW_PRIVATE=1` — opt out of the private-network guard; only for hosts you trust, e.g. internal corporate APIs.
|
|
262
|
+
|
|
263
|
+
MCP-specific behavior: URLs resolving to loopback/private/link-local addresses are rejected by default (MCP clients supply URLs on the model's behalf); diagnostics go to stderr, protocol frames to stdout.
|
|
182
264
|
|
|
183
|
-
|
|
265
|
+
### Authentication headers (CLI)
|
|
184
266
|
|
|
185
267
|
```bash
|
|
186
|
-
npx swagger-digest --url https://api.example.com/swagger-ui
|
|
187
|
-
|
|
268
|
+
npx swagger-digest --url https://api.example.com/swagger-ui \
|
|
269
|
+
--header "Authorization: Bearer eyJhbGciOi..." --out-dir ./docs
|
|
188
270
|
|
|
189
|
-
|
|
271
|
+
# or a session cookie
|
|
272
|
+
npx swagger-digest --url https://api.example.com/swagger-ui --cookie "session=abc123"
|
|
190
273
|
|
|
191
|
-
|
|
274
|
+
# or the environment variable (-H flags win on conflicts)
|
|
192
275
|
export SWAGGER_DIGEST_HEADER=$'Authorization: Bearer eyJ…\nX-Tenant: acme'
|
|
193
276
|
npx swagger-digest --url https://api.example.com/swagger-ui
|
|
194
277
|
```
|
|
195
278
|
|
|
196
|
-
**Scoping and safety:**
|
|
197
|
-
|
|
198
|
-
- Custom headers are sent **only** to the origin of the URL you supply. If the discovered spec, a redirect, or a Swagger UI script lives on a different origin, that request is made without your headers and a warning naming the other origin is printed to stderr.
|
|
199
|
-
- In the headless-browser fallback, headers are injected per-request (only for your origin) — they never reach CDNs or third-party scripts loaded by the page.
|
|
200
|
-
- Header values are never logged, written to the digest, or included in error messages.
|
|
201
|
-
- ⚠️ **Shell history:** secrets passed with `-H` can end up in your shell history file (`~/.bash_history`, `~/.zsh_history`). Prefer the `SWAGGER_DIGEST_HEADER` environment variable, or prefix the command with a space if your shell is configured to ignore leading-space entries.
|
|
279
|
+
**Scoping and safety:** custom headers are sent **only** to the origin of the URL you supply; cross-origin requests (redirects, discovered specs on other origins) proceed without them and produce a warning naming the other origin. In the headless-browser fallback, headers are injected per-request for your origin only — they never reach CDNs or third-party scripts. Header values are never logged, written to the digest, or included in error messages. Secrets passed with `-H` can end up in shell history — prefer the environment variable.
|
|
202
280
|
|
|
203
|
-
###
|
|
281
|
+
### Programmatic API
|
|
204
282
|
|
|
205
|
-
|
|
283
|
+
```ts
|
|
284
|
+
import { fetchOpenApiSpec, transformOpenApiToMarkdown, estimateTokens } from 'swagger-digest';
|
|
206
285
|
|
|
207
|
-
|
|
208
|
-
|
|
286
|
+
const { spec, sourceUrl } = await fetchOpenApiSpec('https://api.example.com/openapi.json', {
|
|
287
|
+
blockPrivateNetworks: true, // recommended when URLs come from untrusted input
|
|
288
|
+
headers: { Authorization: 'Bearer …' },
|
|
289
|
+
});
|
|
290
|
+
const markdown = transformOpenApiToMarkdown(spec, sourceUrl, {
|
|
291
|
+
includeTags: ['Subscriptions'],
|
|
292
|
+
maxTokens: 50_000,
|
|
293
|
+
onWarning: console.warn,
|
|
294
|
+
});
|
|
295
|
+
console.log(estimateTokens(markdown).models.claude.tokens);
|
|
209
296
|
```
|
|
210
297
|
|
|
211
|
-
|
|
298
|
+
`transformOpenApiToMarkdown` options: `includeTags`, `excludeTags`, `pathPrefix`, `maxTokens`, `autoTrim` (default true), `onWarning`. `fetchOpenApiSpec` options include `specUrl`, `headers`, `maxBytes`, `blockPrivateNetworks`, `useBrowserFallback`.
|
|
212
299
|
|
|
213
|
-
|
|
300
|
+
### Trimming order
|
|
214
301
|
|
|
215
|
-
|
|
302
|
+
When a budget applies (explicit `--max_tokens` or the default cap), the digest is trimmed in this fixed order, re-checked after each step: 1) drop declared example payloads → 2) shorten long descriptions → 3) collapse parameter/response detail per tag (the tag appearing last in the document is collapsed first) → 4) keep only the Quick index. A `## Trimmed` note records exactly which steps applied; schemas referenced only by removed operations are dropped. The estimator is a heuristic — treat budgets as a guide, not a guarantee.
|
|
216
303
|
|
|
217
|
-
|
|
304
|
+
## Supported specifications and limitations
|
|
218
305
|
|
|
219
|
-
**
|
|
306
|
+
**Supported:** OpenAPI 2.0, 3.0 and 3.1, in JSON or YAML, fetched over HTTP(S) from direct spec URLs or discovered through Swagger UI pages.
|
|
220
307
|
|
|
221
|
-
|
|
308
|
+
**Limitations:**
|
|
222
309
|
|
|
223
|
-
The
|
|
224
|
-
|
|
225
|
-
-
|
|
226
|
-
- A compact
|
|
227
|
-
- Endpoint details grouped by tag, including auth requirements, path/query/header parameters, request bodies, success/error responses, and JSON example values.
|
|
228
|
-
- TypeScript-like interface/type declarations for schemas reachable from the documented operations, with local `$ref` dependencies expanded as named type references rather than copied JSON Schema trees.
|
|
310
|
+
- The tool downloads specs exposed by the supplied server. It does not bypass authentication, browser access controls, or network restrictions. Ordinary HTTP fetches use Node.js networking — they do not reuse a browser's VPN extension, cookies, or signed-in session. If a page works in Chrome but not here, test `curl -v -L '<url>'` from the terminal; if that fails too, route the terminal through your VPN/proxy.
|
|
311
|
+
- External `$ref` documents are bundled best-effort (one level deep, at most 5 documents); unreachable references degrade to named type references and the digest still succeeds.
|
|
312
|
+
- Very large specs: fetches are capped at 10 MB by default (`--max-bytes`), and digests are capped at ~250k estimated tokens by default (see trimming above).
|
|
313
|
+
- A generated digest is a compact developer reference, not a replacement for the source OpenAPI contract.
|
|
229
314
|
|
|
230
|
-
|
|
315
|
+
**Security notes:** the tool fetches the URL you supply, same-origin Swagger UI initializer/config scripts, the spec URL referenced by that page, and a short list of common spec paths on the same origin. Cookies and Authorization headers are never sent automatically. If you call `fetchOpenApiSpec` from a server that accepts user-supplied URLs, enable `blockPrivateNetworks: true` — without it a caller can point the tool at cloud-metadata or other internal addresses (SSRF); the check rejects loopback, link-local, private, and unique-local addresses after redirects, but has a documented DNS-rebinding limitation — for hostile multi-tenant input, use a dedicated egress proxy. The MCP server enables this guard by default.
|
|
231
316
|
|
|
232
|
-
## Development
|
|
317
|
+
## Development and contribution
|
|
233
318
|
|
|
234
319
|
```bash
|
|
235
320
|
npm install
|
|
236
321
|
npm run build
|
|
237
|
-
npm test
|
|
322
|
+
npm test # typecheck + test suite (runs offline against fixtures)
|
|
238
323
|
npm run lint
|
|
239
|
-
npm link
|
|
240
|
-
swagger-digest
|
|
324
|
+
npm link # then: swagger-digest / swagger-digest-mcp
|
|
241
325
|
```
|
|
242
326
|
|
|
243
|
-
|
|
327
|
+
Manual check against a live API:
|
|
244
328
|
|
|
245
329
|
```bash
|
|
246
330
|
npm run build
|
|
247
331
|
node dist/cli.js --url https://petstore.swagger.io/ --out-dir ./tmp --filename petstore-digest.md
|
|
248
332
|
```
|
|
249
333
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
## Project layout
|
|
334
|
+
Project layout:
|
|
253
335
|
|
|
254
336
|
```text
|
|
255
337
|
src/
|
|
@@ -264,13 +346,6 @@ src/
|
|
|
264
346
|
digest.ts Tool handler: fetch → transform → tool result
|
|
265
347
|
```
|
|
266
348
|
|
|
267
|
-
## Limitations
|
|
268
|
-
|
|
269
|
-
- The tool downloads specs exposed by the supplied server. It does not bypass authentication, browser access controls, or network restrictions.
|
|
270
|
-
- External `$ref` documents are bundled best-effort: references to other HTTP(S) documents are fetched (one level deep, at most 5 documents) and their schemas inlined under namespaced names such as `meta_SharedMeta`. If an external document is unreachable or unparsable, the reference degrades to a named type reference and the digest still succeeds.
|
|
271
|
-
- Declared request/response examples are preserved. When an example is absent but a schema exists, a representative JSON example is generated from that schema and clearly marked as illustrative rather than spec-authored. The transformer includes the primary success response and applicable common error responses to balance useful payload context against digest size.
|
|
272
|
-
- A generated digest is a compact developer reference, not a replacement for the source OpenAPI contract.
|
|
273
|
-
|
|
274
349
|
## License
|
|
275
350
|
|
|
276
351
|
MIT
|