swaggerhub-cli 0.15.0 → 0.16.0

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/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "swaggerhub-cli",
3
- "description": "SwaggerHub CLI",
4
- "version": "0.15.0",
3
+ "description": "SwaggerHub CLI. Includes an agent skill",
4
+ "version": "0.16.0",
5
5
  "author": "SmartBear",
6
6
  "bin": {
7
7
  "swaggerhub": "./bin/run"
@@ -13,7 +13,6 @@
13
13
  "@oclif/plugin-plugins": "^5.0.21",
14
14
  "archiver": "^8.0.0",
15
15
  "deep-extend": "^0.6.0",
16
- "fs-extra": "^11.1.1",
17
16
  "http-proxy-agent": "^9.1.0",
18
17
  "https-proxy-agent": "^9.1.0",
19
18
  "inquirer": "^8.2.5",
@@ -25,6 +24,7 @@
25
24
  "unzipper": "^0.12.3"
26
25
  },
27
26
  "devDependencies": {
27
+ "@eslint/js": "^10.0.1",
28
28
  "@faker-js/faker": "^10.0.0",
29
29
  "@oclif/test": "^3.2.15",
30
30
  "c8": "^12.0.0",
@@ -37,7 +37,6 @@
37
37
  "husky": "^9.0.1",
38
38
  "mocha": "^11.7.6",
39
39
  "nock": "^14.0.1",
40
- "rewire": "^9.0.1",
41
40
  "sinon": "^22.0.0"
42
41
  },
43
42
  "engines": {
@@ -52,11 +51,15 @@
52
51
  "/bin",
53
52
  "/npm-shrinkwrap.json",
54
53
  "/oclif.manifest.json",
55
- "/src"
54
+ "/src",
55
+ "/skills"
56
56
  ],
57
57
  "homepage": "https://github.com/SmartBear/swaggerhub-cli",
58
58
  "keywords": [
59
- "oclif"
59
+ "oclif",
60
+ "agent-skill",
61
+ "claude-code",
62
+ "swagger"
60
63
  ],
61
64
  "license": "Apache-2.0",
62
65
  "main": "src/index.js",
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: swaggerhub-cli
3
+ description: Use the Swagger CLI (`swaggerhub`) to manage APIs, domains, projects, integrations and Spectral rulesets in Swagger (SwaggerHub) from the terminal or CI. Use when asked to fetch, create, update, clone, fork, publish, validate or delete an API or domain definition on Swagger.
4
+ ---
5
+
6
+ # Swagger CLI (`swaggerhub`)
7
+
8
+ Install: `npm i -g swaggerhub-cli` (Node.js >= 22.9). Run `swaggerhub <command> --help` for exact flags; it is the source of truth.
9
+
10
+ ## Authentication
11
+
12
+ Set `SWAGGERHUB_API_KEY` (required). For Swagger Studio On-Premise 2.x also set `SWAGGERHUB_URL=https://<host>/v1`. Never print or commit the key. Alternatively `swaggerhub configure` (interactive, so avoid it in non-interactive agent runs; use env vars).
13
+
14
+ ## Identifiers
15
+
16
+ - API / domain: `OWNER/NAME/VERSION` (VERSION optional on get/update/delete/validate; the default version is used).
17
+ - Project: `OWNER/PROJECT_NAME`.
18
+ - Integration: `OWNER/API_NAME/VERSION/INTEGRATION_ID`.
19
+
20
+ ## Common tasks
21
+
22
+ ```sh
23
+ swaggerhub api:get org/api/1.0.0 --json # YAML by default; -r for resolved definition
24
+ swaggerhub api:create org/api/1.0.0 -f api.yaml # errors if the version already exists
25
+ swaggerhub api:update org/api/1.0.0 -f api.yaml # --published=publish|unpublish, --setdefault, --visibility
26
+ swaggerhub api:clone org/api/1.0.0 1.0.1
27
+ swaggerhub api:fork org/api/1.0.0 myorg/api-fork/1.0.0 # --project, --visibility
28
+ swaggerhub api:comment:list org/api/1.0.0 # table of comments; --json for full detail
29
+ swaggerhub api:publish org/api/1.0.0 --force # --force skips the confirmation prompt
30
+ swaggerhub api:validate org/api/1.0.0 -c -j # -c exits 1 on critical errors, -j prints JSON
31
+ swaggerhub api:validate:local -o org -f api.yaml -c
32
+ swaggerhub project:list org
33
+ ```
34
+
35
+ The `domain:*` commands mirror `api:*` (get, create, update, clone, fork, publish, unpublish, setdefault, rename, delete). Other groups: `project:*` (create, get, list, delete, api/domain add/remove, member:list), `integration:*` (create, get, list, update, delete, execute), `spectral:download|upload`. Use `swaggerhub help` to list everything.
36
+
37
+ ## Guidance for agents
38
+
39
+ - Commands that prompt for confirmation (`api:publish`, `api:delete`, and their domain equivalents) hang without a TTY. Pass `--force`/`-f` only after the user has agreed to the action.
40
+ - Deletes, publishes and unpublishes affect shared, live resources. Confirm with the user before running them, and prefer `api:get` first to check the target exists.
41
+ - Prefer `--json` where available for output you need to parse.
42
+ - To edit a definition: `api:get` to a file, modify it, then `api:update -f`. Run `api:validate:local` before publishing.
43
+ - A non-zero exit code means failure; read stderr rather than retrying blindly.
@@ -0,0 +1,91 @@
1
+ import { Args, Flags, ux } from '@oclif/core'
2
+ import { getApiIdentifierArg } from '../../../support/command/parse-input.js'
3
+ import { hasJsonStructure, prettyPrintJSON } from '../../../utils/general.js'
4
+ import { getApi } from '../../../requests/api.js'
5
+ import BaseCommand from '../../../support/command/base-command.js'
6
+
7
+ const toRow = comment => ({
8
+ id: comment.id,
9
+ user: comment.user?.id ?? '',
10
+ status: comment.status ?? '',
11
+ line: comment.range?.startLine ?? '',
12
+ replies: (comment.replies ?? []).length,
13
+ created: comment.created,
14
+ body: (comment.body ?? '').replaceAll(/\s+/g, ' ')
15
+ })
16
+
17
+ class ListApiCommentsCommand extends BaseCommand {
18
+ constructor(...props) {
19
+ super(...props)
20
+ this.logComments = this.logComments.bind(this)
21
+ }
22
+
23
+ async logComments(response) {
24
+ // the server answers 204 with an empty body when a version has no comments
25
+ const content = (await response.content) || '[]'
26
+
27
+ if (this.jsonOutput || !hasJsonStructure(content)) {
28
+ this.log(hasJsonStructure(content) ? prettyPrintJSON(content) : content)
29
+ return
30
+ }
31
+
32
+ const comments = JSON.parse(content)
33
+ if (!Array.isArray(comments)) {
34
+ this.log(prettyPrintJSON(content))
35
+ return
36
+ }
37
+
38
+ if (comments.length === 0) {
39
+ this.log('No comments found.')
40
+ return
41
+ }
42
+
43
+ ux.table(comments.map(toRow), {
44
+ id: {},
45
+ user: {},
46
+ status: {},
47
+ line: {},
48
+ replies: {},
49
+ created: {},
50
+ body: {}
51
+ }, {
52
+ printLine: this.log.bind(this)
53
+ })
54
+ }
55
+
56
+ async run() {
57
+ const { args, flags } = await this.parse(ListApiCommentsCommand)
58
+ const apiPath = getApiIdentifierArg(args)
59
+ this.jsonOutput = flags.json
60
+
61
+ await this.executeHttp({
62
+ execute: () => getApi([apiPath, 'comments']),
63
+ onResolve: this.logComments,
64
+ options: {}
65
+ })
66
+ }
67
+ }
68
+
69
+ ListApiCommentsCommand.description = 'list the comments of an API version'
70
+
71
+ ListApiCommentsCommand.examples = [
72
+ 'swaggerhub api:comment:list organization/api/1.0.0',
73
+ 'swaggerhub api:comment:list organization/api/1.0.0 --json'
74
+ ]
75
+
76
+ ListApiCommentsCommand.args = {
77
+ 'OWNER/API_NAME/VERSION': Args.string({
78
+ required: true,
79
+ description: 'API version to list comments for'
80
+ })
81
+ }
82
+
83
+ ListApiCommentsCommand.flags = {
84
+ json: Flags.boolean({
85
+ char: 'j',
86
+ description: 'prints the comments, including replies and ranges, as JSON'
87
+ }),
88
+ ...BaseCommand.flags
89
+ }
90
+
91
+ export default ListApiCommentsCommand
@@ -0,0 +1,75 @@
1
+ import BaseCommand from '../../support/command/base-command.js'
2
+ import { Args, Flags, Errors } from '@oclif/core'
3
+ import { getApiIdentifierArg, splitPathParams } from '../../support/command/parse-input.js'
4
+ import { errorMsg } from '../../template-strings/index.js'
5
+ import { postApi } from '../../requests/api.js'
6
+
7
+ const { CLIError } = Errors
8
+
9
+ const targetRegex = new RegExp(/^[\w\-.]+\/[\w\-.]+\/[\w\-.]+$/)
10
+
11
+ const getTarget = args => {
12
+ const target = args['NEW_OWNER/NEW_API_NAME/NEW_VERSION']
13
+ if (!targetRegex.test(target)) {
14
+ throw new CLIError(errorMsg.argsMustMatchFormat({ format: 'NEW_OWNER/NEW_API_NAME/NEW_VERSION' }))
15
+ }
16
+ const [owner, name, version] = splitPathParams(target)
17
+ return { owner, name, version }
18
+ }
19
+
20
+ class ForkApiCommand extends BaseCommand {
21
+
22
+ async run() {
23
+ const { args, flags } = await this.parse(ForkApiCommand)
24
+
25
+ const apiPath = getApiIdentifierArg(args)
26
+ const body = getTarget(args)
27
+ const forkPath = `${body.owner}/${body.name}/${body.version}`
28
+ if (flags.project) body.project = flags.project
29
+ if (flags.visibility) body.private = flags.visibility === 'private'
30
+
31
+ this.log(`Forking API: '${apiPath}' as '${forkPath}'`)
32
+
33
+ await this.executeHttp({
34
+ execute: () => postApi({
35
+ pathParams: [apiPath, 'fork'],
36
+ body: JSON.stringify(body)
37
+ }),
38
+ onResolve: this.logCommandSuccess({ apiPath, forkPath }),
39
+ options: {}
40
+ })
41
+ }
42
+ }
43
+
44
+ ForkApiCommand.description = `fork an API version
45
+ The fork can be created as a new API, or as a new version of another existing API.
46
+ `
47
+
48
+ ForkApiCommand.examples = [
49
+ 'swaggerhub api:fork organization/api/1.0.0 myorg/api-fork/1.0.0',
50
+ 'swaggerhub api:fork organization/api/1.0.0 myorg/api-fork/1.0.0 --project my-project --visibility private'
51
+ ]
52
+
53
+ ForkApiCommand.args = {
54
+ 'OWNER/API_NAME/VERSION': Args.string({
55
+ required: true,
56
+ description: 'API version to fork'
57
+ }),
58
+ 'NEW_OWNER/NEW_API_NAME/NEW_VERSION': Args.string({
59
+ required: true,
60
+ description: 'Owner, name and version of the fork. An existing API name creates a new version of it.'
61
+ })
62
+ }
63
+
64
+ ForkApiCommand.flags = {
65
+ project: Flags.string({
66
+ description: 'existing project of the target organization to add the fork to'
67
+ }),
68
+ visibility: Flags.string({
69
+ description: 'visibility of the fork (defaults to the visibility of the source version)',
70
+ options: ['public', 'private']
71
+ }),
72
+ ...BaseCommand.flags
73
+ }
74
+
75
+ export default ForkApiCommand
@@ -0,0 +1,75 @@
1
+ import BaseCommand from '../../support/command/base-command.js'
2
+ import { Args, Flags, Errors } from '@oclif/core'
3
+ import { getDomainIdentifierArg, splitPathParams } from '../../support/command/parse-input.js'
4
+ import { errorMsg } from '../../template-strings/index.js'
5
+ import { postDomain } from '../../requests/domain.js'
6
+
7
+ const { CLIError } = Errors
8
+
9
+ const targetRegex = new RegExp(/^[\w\-.]+\/[\w\-.]+\/[\w\-.]+$/)
10
+
11
+ const getTarget = args => {
12
+ const target = args['NEW_OWNER/NEW_DOMAIN_NAME/NEW_VERSION']
13
+ if (!targetRegex.test(target)) {
14
+ throw new CLIError(errorMsg.argsMustMatchFormat({ format: 'NEW_OWNER/NEW_DOMAIN_NAME/NEW_VERSION' }))
15
+ }
16
+ const [owner, name, version] = splitPathParams(target)
17
+ return { owner, name, version }
18
+ }
19
+
20
+ class ForkDomainCommand extends BaseCommand {
21
+
22
+ async run() {
23
+ const { args, flags } = await this.parse(ForkDomainCommand)
24
+
25
+ const domainPath = getDomainIdentifierArg(args)
26
+ const body = getTarget(args)
27
+ const forkPath = `${body.owner}/${body.name}/${body.version}`
28
+ if (flags.project) body.project = flags.project
29
+ if (flags.visibility) body.private = flags.visibility === 'private'
30
+
31
+ this.log(`Forking domain: '${domainPath}' as '${forkPath}'`)
32
+
33
+ await this.executeHttp({
34
+ execute: () => postDomain({
35
+ pathParams: [domainPath, 'fork'],
36
+ body: JSON.stringify(body)
37
+ }),
38
+ onResolve: this.logCommandSuccess({ domainPath, forkPath }),
39
+ options: {}
40
+ })
41
+ }
42
+ }
43
+
44
+ ForkDomainCommand.description = `fork a domain version
45
+ The fork can be created as a new domain, or as a new version of another existing domain.
46
+ `
47
+
48
+ ForkDomainCommand.examples = [
49
+ 'swaggerhub domain:fork organization/domain/1.0.0 myorg/domain-fork/1.0.0',
50
+ 'swaggerhub domain:fork organization/domain/1.0.0 myorg/domain-fork/1.0.0 --project my-project --visibility private'
51
+ ]
52
+
53
+ ForkDomainCommand.args = {
54
+ 'OWNER/DOMAIN_NAME/VERSION': Args.string({
55
+ required: true,
56
+ description: 'Domain version to fork'
57
+ }),
58
+ 'NEW_OWNER/NEW_DOMAIN_NAME/NEW_VERSION': Args.string({
59
+ required: true,
60
+ description: 'Owner, name and version of the fork. An existing domain name creates a new version of it.'
61
+ })
62
+ }
63
+
64
+ ForkDomainCommand.flags = {
65
+ project: Flags.string({
66
+ description: 'existing project of the target organization to add the fork to'
67
+ }),
68
+ visibility: Flags.string({
69
+ description: 'visibility of the fork (defaults to the visibility of the source version)',
70
+ options: ['public', 'private']
71
+ }),
72
+ ...BaseCommand.flags
73
+ }
74
+
75
+ export default ForkDomainCommand
@@ -1,4 +1,4 @@
1
- import fse from 'fs-extra' // We're not using {readSyncJSON, ...} expansion, since we want to mock it.
1
+ import fs from 'node:fs'
2
2
  import { mergeDeep, pick } from '../utils/general.js'
3
3
 
4
4
  const swaggerhubUrlRegex = new RegExp(/^https?:\/\/api\..*swaggerhub\.com$/)
@@ -15,14 +15,20 @@ const stripTrailingSlashes = config => (
15
15
  : config
16
16
  )
17
17
 
18
+ // A mutable object keeps file access stubbable in tests (ES module namespaces are frozen).
19
+ const fileIO = {
20
+ readJSON: filePath => JSON.parse(fs.readFileSync(filePath, 'utf8')),
21
+ writeJSON: (filePath, data) => fs.writeFileSync(filePath, `${JSON.stringify(data)}\n`)
22
+ }
23
+
18
24
  const getConfig = () => {
19
25
  const { configFilePath } = global
20
- return stripTrailingSlashes(checkEnvOverrides(fse.readJSONSync(configFilePath)))
26
+ return stripTrailingSlashes(checkEnvOverrides(fileIO.readJSON(configFilePath)))
21
27
  }
22
28
 
23
29
  const setConfig = update => {
24
30
  const { configFilePath } = global
25
- return fse.writeJSONSync(configFilePath, mergeDeep(fse.readJSONSync(configFilePath), update))
31
+ return fileIO.writeJSON(configFilePath, mergeDeep(fileIO.readJSON(configFilePath), update))
26
32
  }
27
33
 
28
34
  const isURLValid = () => {
@@ -35,6 +41,7 @@ const isURLValid = () => {
35
41
 
36
42
  // A mutable default export keeps these functions stubbable (ES module namespaces are frozen).
37
43
  const config = {
44
+ fileIO,
38
45
  setConfig,
39
46
  getConfig,
40
47
  isURLValid
@@ -42,6 +49,7 @@ const config = {
42
49
 
43
50
  export default config
44
51
  export {
52
+ fileIO,
45
53
  setConfig,
46
54
  getConfig,
47
55
  isURLValid
@@ -1,13 +1,14 @@
1
1
  import path from 'path'
2
- import { existsSync } from 'node:fs'
3
- import fse from 'fs-extra'
2
+ import fs, { existsSync } from 'node:fs'
4
3
  import packageJson from '../../package.json' with { type: 'json' }
5
4
  import { pipe } from '../utils/general.js'
6
5
 
7
- const { outputJsonSync } = fse
8
6
  const { configDefaults } = packageJson.oclif
9
7
 
10
- const createConfigFile = (filePath, config) => outputJsonSync(filePath, config, { mode: 0o600 })
8
+ const createConfigFile = (filePath, config) => {
9
+ fs.mkdirSync(path.dirname(filePath), { recursive: true })
10
+ fs.writeFileSync(filePath, `${JSON.stringify(config)}\n`, { mode: 0o600 })
11
+ }
11
12
 
12
13
  const createConfigPath = ({ configDir }) => path.join(configDir, 'config.json')
13
14
 
@@ -9,8 +9,12 @@ const infoMsg = {
9
9
 
10
10
  ApiClone: 'Cloned API \'{{apiPath}}\' as version {{newVersion}}',
11
11
 
12
+ ApiFork: 'Forked API \'{{apiPath}}\' as \'{{forkPath}}\'',
13
+
12
14
  DomainClone: 'Cloned domain \'{{domainPath}}\' as version {{newVersion}}',
13
15
 
16
+ DomainFork: 'Forked domain \'{{domainPath}}\' as \'{{forkPath}}\'',
17
+
14
18
  DomainRename: 'Renamed domain \'{{domainPath}}\' to \'{{newName}}\'',
15
19
 
16
20
  DomainCreate: 'Created domain \'{{owner}}/{{name}}\'',