Jason-chen-coder Swagger Doc Skill
Read references/dev-baseline.md once per task. Use the bundled Node.js extractor
for consistent discovery, schema resolution, and exports. Resolve <skill-dir>
to the absolute directory containing this SKILL.md.
Document Source
- Use the docs URL, local specification, or config path provided in this request.
- Reuse an unambiguous source already confirmed in this chat for follow-ups.
- If several sources remain plausible, ask which one applies. If none is available, ask for a Swagger/OpenAPI URL, local spec, or config path.
Do not inherit Swagger sources across chats. Do not guess documentation URLs, scan unrelated hosts, or invent endpoints. If the task is about an SDK without an OpenAPI source, use its official documentation workflow instead.
The script only reads config files when --config <path> is passed explicitly.
Do not rely on shared defaults or persist chat URLs, tokens, or headers into the
skill's configuration. Keep credential-bearing project configs untracked.
Do not expose secret values in commands shown to the user, logs, or documents.
State the active source with the result, redacting URL credentials or tokens.
Query Workflow
Choose the smallest output that answers the request:
| Intent | Script mode and filters |
|---|---|
| Modules/tags/controllers | --mode modules |
| Endpoint list | --mode endpoints; narrow with --tag, --method, --path, --search |
| One endpoint's request/response | --mode endpoint --path <path> --method <METHOD> |
| Feature integration | Find candidates with endpoints, then use integration with the matched method/path |
| Reusable types/models/DTOs | --mode types; narrow with --type or --search |
| Full export | --mode document --output <file.md>; add --format json for JSON |
node "<skill-dir>/scripts/extract_swagger_docs.mjs" "<docs-url-or-local-spec>" --mode modules
node "<skill-dir>/scripts/extract_swagger_docs.mjs" "<source>" --mode endpoints --search "登录"
node "<skill-dir>/scripts/extract_swagger_docs.mjs" "<source>" --mode integration --path "/api/user/login" --method POST
node "<skill-dir>/scripts/extract_swagger_docs.mjs" --config ./swagger.config.json --mode document --output swagger-api.md
For a UI page, let the extractor discover its backing specification. Review the requested result against the extracted methods, paths, and schemas. Output size should follow the request: a single field question does not need a full export.
For feature lookup, --search includes common Chinese/English intent synonyms.
Use endpoint descriptions and the user's context to narrow candidates. Ask only
when materially different candidates remain plausible; multiple text matches
alone do not require a question. If no match exists, try a few relevant adjacent
terms, then report the gap. Integration guidance requires an endpoint actually
present in the confirmed spec.
Output And Verification
Preserve exact HTTP methods, paths, schema names, required fields, enum/default
values, content types, response statuses, base URLs, and documented auth.
Resolve local $ref and legacy originalRef where possible. Full exports include
reusable components.schemas / Swagger 2 definitions, not just endpoint
summaries. Mark unresolved references and recursive expansion limits.
Generated request examples and fields inferred from examples are illustrations, not additional contract guarantees. Missing auth documentation does not prove that the deployed endpoint is public. Do not execute generated API calls merely to verify documentation.
For full exports, check source/module/endpoint/type counts, required sections, and unresolved schemas. For focused queries, verify the selected endpoint or type and its relevant fields. A successful extraction proves what the source documents, not production behavior or server reachability.
Read references/output-format.md for full export sections, schema formatting, and integration-example requirements. Read references/extractor-usage.md for config, cache, headers, detailed command options, and discovery failures.
Runtime And Failures
JSON specs and Swagger UI extraction use Node.js built-ins. Direct YAML input
requires the optional yaml package; if unavailable, use an available JSON
export or report the dependency and request the missing source as needed.
If a reachable docs page cannot be resolved, inspect its configuration/network for a direct spec and retry that evidenced URL. If the input URL itself times out or fails to fetch, report the failure instead of probing many fallback paths. For authentication failures, use existing authorized access or request an export or suitable credential mechanism. Keep partial results and unresolved items explicit; never fill missing schemas or endpoint meaning from memory.
SDD Evidence Contract
Use the active source, exact method/path, request shape, and response schema as evidence for an existing spec or plan. Cite the endpoint and source in a handoff. Report conflicts with a plan, generated client, or local DTO explicitly. Documentation lookup alone does not authorize editing SDD artifacts or clients; make those changes when they are part of the user's requested implementation.
Multi-Agent Profile
Recommended agent_type: explorer
Delegate only when available and useful for a bounded, independent extraction. Provide the confirmed source and requested endpoint/type or export scope. The worker inherits source isolation and secret handling above and returns the active source, requested result/file, verification command, and relevant counts or unresolved schemas. It does not infer endpoints or expand into API writes.
When running from this repository, use ../../docs/multi-agent-policy.md as
the extended policy. Standalone installs rely on this profile and do not require
that repository file.