Skip to content

feat(portal): adds new portal toc command and various improvements #93

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
saeedjamshaid merged 11 commits into from
Jun 24, 2025
Merged

feat(portal): adds new portal toc command and various improvements #93

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
76b0443
fix(portal): various improvements for portal commands (#59)
aliasghar98 May 23, 2025
a703fdf
refactor: improved portal generate command and updated sdk version (#61)
aliasghar98 Jun 5, 2025
78f2ece
fix: improves portal generate error messaging (#80)
aliasghar98 Jun 17, 2025
4f154cb
fix(sdk): updated sdk generation platform names and added golang (#79)
aliasghar98 Jun 17, 2025
f3d9895
feat(new-command): add new command: portal:new:toc (#83)
saeedjamshaid Jun 17, 2025
baa7ca9
feat: updates apimatic sdk with recommended codegen settings (#89)
aliasghar98 Jun 20, 2025
37fbcb0
test(portal:new:toc): add tests for the portal:new:toc command (#86)
saeedjamshaid Jun 23, 2025
8bee7b8
feat: add published sdk dependency (#94)
aliasghar98 Jun 23, 2025
016881e
docs: update readme file with new toc command instructions (#95)
saeedjamshaid Jun 23, 2025
926dea9
chore: update package version to 1.1.0-alpha.7
saeedjamshaid Jun 23, 2025
30f4a0d
Merge branch 'alpha' into dev
saeedjamshaid Jun 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,4 +174,7 @@ $RECYCLE.BIN/
# Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option)

lib/
tmp/
tmp/
.vscode/launch.json
test-source/
test-portal/
81 changes: 81 additions & 0 deletions .vscode/launch.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Debug APIMatic CLI",
"skipFiles": ["<node_internals>/"],
"program": "${workspaceFolder}/bin/run",
"args": [
// "api:validate",
// "--file=C:/Users/User/Desktop/spec/Errors.yaml",
// "--file=https://petstore.swagger.io/v2/swagger.json"
// "api:transform",
// "--format=OpenApi3Json",
// "--file=C:/Users/User/Desktop/test-cli/spec/Calculator.json",
// "--destination=C:/Users/User/Desktop/test-cli/spec"
// "auth:logout",
// "auth:login",
// "auth:status"
// "portal:quickstart",
// "portal:generate",
// "portal:new:toc",
//"--expand-endpoints",
//"--expand-models",
// "--force",
// "--folder",
// "test-source",
// "--destination",
// "test-portal",
// "portal:serve",
// "api:transform",
// "--help"
// "--folder=C:/Users/User/Desktop/demo/portal",
// "--destination=C:\\Users\\User\\Desktop\\demo\\portal\\api-portal"
// "--source=C:/Users/User/Desktop/demo/portal/",
// "--destination=C:/Users/User/Desktop/demo/portal/api-portal2",
// "--source=C:/Users/User/Desktop/demo/portal",
// "--source=\"C:\\Users\\User\\Desktop\\test-cli\"",
// "--destination=\"C:\\Users\\User\\Desktop\\demo\\portal\\api-portal\"",
// "--destination=\"C:\\Users\\User\\Desktop\\demo\\api-portal\"",
// "--source=C:/Users/User/Desktop/test-cli",
// "--destination=C:/Users/User/Desktop/test-cli/api-portal",
// "--source=C:\\Users\\User\\Desktop\\test-cli-2",
// "--destination=C:\\Users\\User\\Desktop\\test-cli-2\\generated_portal"
// "--port=70000"
// "--ignore=C:/Users/User/Desktop/demo/portal/content,C:/Users/User/Desktop/demo/portal/static/images/logo.png",
// "--no-reload",
// "--auth-key=\"invalidApiKey\"",
// "--help"
],
"console": "externalTerminal",
"preLaunchTask": "tsc: build - tsconfig.json"
},
{
"type": "node",
"request": "launch",
"name": "Debug CLI Tests",
"program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
"args": [
"--require",
"ts-node/register",
"--project",
"${workspaceFolder}/tsconfig.json",
"--forbid-only",
"test/**/*.test.ts",
"--timeout",
"99999",
],
"cwd": "${workspaceFolder}",
"runtimeArgs": [
"--nolazy",
"--inspect-brk",
"--trace-warnings"
],
"internalConsoleOptions": "openOnSessionStart",
"skipFiles": ["<node_internals>/**"],
"console": "integratedTerminal"
}
]
}
132 changes: 85 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,18 +17,14 @@ To get started with APIMatic's CLI using a step by step wizard, run the followin
$ apimatic portal:quickstart
```

<!-- toc -->
* [Usage](#usage)
* [Commands](#commands)
<!-- tocstop -->
# Usage
<!-- usage -->
```sh-session
$ npm install -g @apimatic/cli
$ apimatic COMMAND
running command...
$ apimatic (--version)
@apimatic/cli/0.0.0-alpha.0 win32-x64 node-v20.18.3
@apimatic/cli/1.1.0-alpha.8 win32-x64 node-v23.4.0
$ apimatic --help [COMMAND]
USAGE
$ apimatic COMMAND
Expand All @@ -46,6 +42,7 @@ USAGE
* [`apimatic autocomplete [SHELL]`](#apimatic-autocomplete-shell)
* [`apimatic help [COMMAND]`](#apimatic-help-command)
* [`apimatic portal:generate`](#apimatic-portalgenerate)
* [`apimatic portal:new:toc`](#apimatic-portalnewtoc)
* [`apimatic portal:quickstart`](#apimatic-portalquickstart)
* [`apimatic portal:serve`](#apimatic-portalserve)
* [`apimatic sdk:generate`](#apimatic-sdkgenerate)
Expand All @@ -61,18 +58,13 @@ USAGE

FLAGS
-f, --force overwrite if same file exist in the destination
--auth-key=auth-key override current authentication state with an authentication key

--destination=destination [default: /home/runner/work/apimatic-cli/apimatic-cli/cli] directory to download
transformed file to

--file=file path to the API specification file to transform

--format=format (required) specification format to transform API specification into
--auth-key=<value> override current authentication state with an authentication key
--destination=<value> [default: ./] directory to download transformed file to
--file=<value> path to the API specification file to transform
--format=<value> (required) specification format to transform API specification into
APIMATIC|WADL2009|WSDL|SWAGGER10|SWAGGER20|SWAGGERYAML|OAS3|OPENAPI3YAML|APIBLUEPRINT|RAML|
RAML10|POSTMAN10|POSTMAN20|GRAPHQLSCHEMA

--url=url URL to the API specification file to transform. Can be used in place of the --file option
--url=<value> URL to the API specification file to transform. Can be used in place of the --file option
if the API specification is publicly available.

DESCRIPTION
Expand All @@ -99,11 +91,10 @@ USAGE
$ apimatic api:validate [--file <value>] [--url <value>] [--auth-key <value>]

FLAGS
--auth-key=auth-key override current authentication state with an authentication key
--file=file Path to the API specification file to validate

--url=url URL to the specification file to validate. Can be used in place of the --file option if the API
specification is publicly available.
--auth-key=<value> override current authentication state with an authentication key
--file=<value> Path to the API specification file to validate
--url=<value> URL to the specification file to validate. Can be used in place of the --file option if the API
specification is publicly available.

DESCRIPTION
Validate the syntactic and semantic correctness of an API specification
Expand All @@ -127,16 +118,15 @@ USAGE
$ apimatic auth:login [--auth-key <value>]

FLAGS
--auth-key=auth-key Set authentication key for all commands
--auth-key=<value> Set authentication key for all commands

DESCRIPTION
Login using your APIMatic credentials or an API Key

EXAMPLES
$ apimatic auth:login
Please enter your registered email: apimatic-user@gmail.com
Enter your registered email: apimatic-user@gmail.com
Please enter your password: *********

You have successfully logged into APIMatic

$ apimatic auth:login --auth-key=xxxxxx
Expand Down Expand Up @@ -213,10 +203,13 @@ Display help for apimatic.

```
USAGE
$ apimatic help [COMMAND]
$ apimatic help [COMMAND...] [-n]

ARGUMENTS
COMMAND command to show help for
COMMAND... Command to show help for.

FLAGS
-n, --nested-commands Include all nested commands in the output.

DESCRIPTION
Display help for apimatic.
Expand All @@ -234,6 +227,11 @@ USAGE

FLAGS
-f, --force overwrite if a portal exists in the destination
--auth-key=<value> override current authentication state with an authentication key
--destination=<value> [default: ./generated_portal] path to the downloaded portal
--folder=<value> [default: ./] path to the input directory containing API specifications and config files
--zip download the generated portal as a .zip archive

DESCRIPTION
Generate and download a static API Documentation portal. Requires an input directory containing API specifications, a
config file and optionally, markdown guides. For details, refer to the [documentation](https://docs.apimatic.io/platfo
Expand All @@ -246,33 +244,78 @@ EXAMPLES

_See code: [src/commands/portal/generate.ts](https://github.com/apimatic/apimatic-cli/blob/alpha/src/commands/portal/generate.ts)_

## `apimatic portal:new:toc`

Generates a TOC file based on the content directory and spec folder provided in your working directory

```
USAGE
$ apimatic portal:new:toc [--destination <value>] [--folder <value>] [--force] [--expand-endpoints]
[--expand-models]

FLAGS
--destination=<value> optional path where the generated TOC file will be saved. Defaults to the current working
directory if not provided.
--expand-endpoints include individual entries for each endpoint in the generated TOC. Requires a valid API
specification in the working directory.
--expand-models include individual entries for each model in the generated TOC. Requires a valid API
specification in the working directory.
--folder=<value> [default: ./] path to the working directory containing the API project
files. Defaults to the current working directory if not specified.
--force overwrite the TOC file if one already exists at the destination.

DESCRIPTION
Generates a TOC file based on the content directory and spec folder provided in your working directory

This command generates a new Table of Contents (TOC) file used in the
generation of your API documentation portal.

The output is a YAML file with the .yml extension.

To learn more about the TOC file and APIMatic build directory structure, visit:
https://docs.apimatic.io/platform-api/#/http/guides/generating-on-prem-api-portal/overview-generating-api-portal

EXAMPLES
$ apimatic portal:new:toc --destination="./portal/content/"
A new toc file has been created at ./portal/content/toc.yml

$ apimatic portal:new:toc --folder="./my-project"
A new toc file has been created at ./my-project/content/toc.yml

$ apimatic portal:new:toc --folder="./my-project" --destination="./portal/content/"
A new toc file has been created at ./portal/content/toc.yml
```

_See code: [src/commands/portal/new/toc.ts](https://github.com/apimatic/apimatic-cli/blob/alpha/src/commands/portal/new/toc.ts)_

## `apimatic portal:quickstart`

Create your first API Portal using APIMatic’s Docs as Code offering.
Create your first API Portal using APIMatic's Docs as Code offering.

```
USAGE
$ apimatic portal:quickstart

DESCRIPTION
Create your first API Portal using APIMatic’s Docs as Code offering.
Create your first API Portal using APIMatic's Docs as Code offering.

EXAMPLES
$ apimatic portal:quickstart
```

_See code: [src/commands/portal/quickstart.ts](https://github.com/apimatic/apimatic-cli/blob/v1.0.1-alpha.11/src/commands/portal/quickstart.ts)_
_See code: [src/commands/portal/quickstart.ts](https://github.com/apimatic/apimatic-cli/blob/alpha/src/commands/portal/quickstart.ts)_

## `apimatic portal:serve`

Generate and deploy a Docs as Code portal with hot reload.

```
USAGE
$ apimatic portal:serve [-p <value>] [-d <value>] [-s <value>] [-o] [--no-reload] [-i <value>] [--auth-key <value>]
$ apimatic portal:serve [-p <value>] [-d <value>] [-s <value>] [-o] [--no-reload] [-i <value>] [--auth-key
<value>]

FLAGS
-d, --destination=<value> [default: ./api-portal] Directory to store and serve the generated portal.
-d, --destination=<value> [default: ./generated_portal] Directory to store and serve the generated portal.
-i, --ignore=<value> Comma-separated list of files/directories to ignore.
-o, --open Open the portal in the default browser.
-p, --port=<value> [default: 3000] Port to serve the portal.
Expand All @@ -285,35 +328,30 @@ DESCRIPTION
Generate and deploy a Docs as Code portal with hot reload.

EXAMPLES
$ apimatic portal:serve --source="./" --destination="./api-portal" --port=3000 --open --no-reload
$ apimatic portal:serve --source="./" --destination="./generated_portal" --port=3000 --open --no-reload
```

_See code: [src/commands/portal/serve.ts](https://github.com/apimatic/apimatic-cli/blob/v1.0.1-alpha.11/src/commands/portal/serve.ts)_
_See code: [src/commands/portal/serve.ts](https://github.com/apimatic/apimatic-cli/blob/alpha/src/commands/portal/serve.ts)_

## `apimatic sdk:generate`

Generate SDK for your APIs

```
USAGE
$ apimatic sdk:generate --platform <value> [--file <value>] [--url <value>] [--destination <value>] [-f] [--zip] [--auth-key <value>]
$ apimatic sdk:generate --platform <value> [--file <value>] [--url <value>] [--destination <value>] [-f] [--zip]
[--auth-key <value>]

FLAGS
-f, --force overwrite if an SDK already exists in the destination
--auth-key=auth-key override current authentication state with an authentication key

--destination=destination [default: /home/runner/work/apimatic-cli/apimatic-cli/cli] directory to download the
generated SDK to

--file=file path to the API specification to generate SDKs for

--platform=platform (required) language platform for sdk
Simple: CSHARP|JAVA|PYTHON|RUBY|PHP|TYPESCRIPT
Legacy: CS_NET_STANDARD_LIB|CS_PORTABLE_NET_LIB|CS_UNIVERSAL_WINDOWS_PLATFORM_LIB|
JAVA_ECLIPSE_JRE_LIB|PHP_GENERIC_LIB|PYTHON_GENERIC_LIB|RUBY_GENERIC_LIB|
TS_GENERIC_LIB

--url=url URL to the API specification to generate SDKs for. Can be used in place of the --file
--auth-key=<value> override current authentication state with an authentication key
--destination=<value> [default: ./] directory to download the generated SDK to
--file=<value> path to the API specification to generate SDKs for
--platform=<value> (required) language platform for sdk
Simple: CSHARP|JAVA|PYTHON|RUBY|PHP|TYPESCRIPT|GO
Legacy: CS_NET_STANDARD_LIB|JAVA_ECLIPSE_JRE_LIB|PHP_GENERIC_LIB_V2|PYTHON_GENERIC_LIB|RUBY
_GENERIC_LIB|TS_GENERIC_LIB|GO_GENERIC_LIB
--url=<value> URL to the API specification to generate SDKs for. Can be used in place of the --file
option if the API specification is publicly available.
--zip download the generated SDK as a .zip archive

Expand Down
Loading