docs: add root level readme (api7#103)

bzp2010 · Jun 5, 2024 · 94f4b31 · 94f4b31
1 parent af43159
commit 94f4b31
Show file tree

Hide file tree

Showing 2 changed files with 71 additions and 127 deletions.
diff --git a/README.md b/README.md
@@ -1,57 +1,97 @@
-# AdcJs
+# API Declarative CLI (ADC)
 
-<a alt="Nx logo" href="https://nx.dev" target="_blank" rel="noreferrer"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-logo.png" width="45"></a>
+ADC is a command line utility to interface with API7 Enterprise and Apache APISIX Admin API.
 
-✨ **This workspace has been generated by [Nx, a Smart, fast and extensible build system.](https://nx.dev)** ✨
+## Supported Backend
 
-## Generate code
+| Backend         | Documentation                           |
+| --------------- | --------------------------------------- |
+| API7 Enterprise | [README](libs/backend-api7/README.md)   |
+| Apache APISIX   | [README](libs/backend-apisix/README.md) |
 
-If you happen to use Nx plugins, you can leverage code generators that might come with it.
+## Supported Converter
 
-Run `nx list` to get a list of available plugins and whether they have generators. Then run `nx list <plugin-name>` to see what generators are available.
+| Converter      | Documentation                              |
+| -------------- | ------------------------------------------ |
+| OpenAPI Spec 3 | [README](libs/converter-openapi/README.md) |
 
-Learn more about [Nx generators on the docs](https://nx.dev/plugin-features/use-code-generators).
+## Installation
 
-## Running tasks
+You can download the appropriate binary from the [releases page](https://github.com/api7/adc/releases):
 
-To execute tasks with Nx use the following syntax:
-
-```
-nx <target> <project> <...options>
+```bash
+wget https://github.com/api7/adc/releases/download/v0.10.0/adc_0.10.0_linux_amd64.tar.gz
+tar -zxvf adc_0.10.0_linux_amd64.tar.gz
+mv adc /usr/local/bin/adc
 ```
 
-You can also run multiple targets:
+Pre-built binaries for `amd64` and `arm64` on Linux, Windows, and macOS are available now.
+
+## Usage
+
+### Initial setup
+
+The easiest way to persist configurations is to use environment variables. You can check the environment variables in `adc help`.
 
+The ADC supports dotenv, so you can create `.env` files to store environment variables.
+
+You need to set the `token` to the ADC so that the ADC can access API7 Enterprise and the Apache APISIX Admin API.
+
+#### API7 Enterprise
+
+```bash
+ADC_BACKEND=api7ee
+ADC_SERVER=https://localhost:7443
+ADC_TOKEN=<generate token on API7 Dashboard>
 ```
-nx run-many -t <target1> <target2>
+
+#### Apache APISIX
+
+```bash
+ADC_SERVER=http://localhost:9180
+ADC_TOKEN=<Admin API key in the configuration file>
 ```
 
-..or add `-p` to filter specific projects
+### Common commands
+
+#### Check connectivity
 
+```bash
+adc ping
 ```
-nx run-many -t <target1> <target2> -p <proj1> <proj2>
+
+#### Dump configurations to ADC format
+
+```bash
+adc dump -o adc.yaml
 ```
 
-Targets can be defined in the `package.json` or `projects.json`. Learn more [in the docs](https://nx.dev/core-features/run-tasks).
+#### Check for differences between local and remote configurations
 
-## Want better Editor Integration?
+```bash
+adc diff -f adc.yaml
+```
 
-Have a look at the [Nx Console extensions](https://nx.dev/nx-console). It provides autocomplete support, a UI for exploring and running tasks & generators, and more! Available for VSCode, IntelliJ and comes with a LSP for Vim users.
+#### Synchronize local configuration
 
-## Ready to deploy?
+```bash
+adc sync -f adc.yaml
+```
+
+#### Convert API configuration
 
-Just run `nx build demoapp` to build the application. The build artifacts will be stored in the `dist/` directory, ready to be deployed.
+For example, it supports the conversion of OpenAPI 3 to ADC configurations.
 
-## Set up CI!
+```bash
+adc convert openapi -f openapi.yaml
+```
 
-Nx comes with local caching already built-in (check your `nx.json`). On CI you might want to go a step further.
+#### Verify ADC configuration
 
-- [Set up remote caching](https://nx.dev/core-features/share-your-cache)
-- [Set up task distribution across multiple machines](https://nx.dev/nx-cloud/features/distribute-task-execution)
-- [Learn more how to setup CI](https://nx.dev/recipes/ci)
+```bash
+adc lint -f adc.yaml
+```
 
-## Connect with us!
+## License
 
-- [Join the community](https://nx.dev/community)
-- [Subscribe to the Nx Youtube Channel](https://www.youtube.com/@nxdevtools)
-- [Follow us on Twitter](https://twitter.com/nxdevtools)
+This project is licensed under the [Apache 2.0 License](LICENSE).
diff --git a/apps/cli/src/command/utils.spec.ts b/apps/cli/src/command/utils.spec.ts
@@ -43,55 +43,13 @@ describe('CLI utils', () => {
               name: 'Test Stream Route',
             },
           ],
-          upstreams: [
-            {
-              name: 'Test Upstream',
-            },
-          ],
-          consumer_groups: [
-            {
-              name: 'Test Consumer Group',
-              plugins: {},
-              consumers: [
-                {
-                  username: 'Test Nested Consumer',
-                },
-              ],
-            },
-          ],
-          plugin_configs: [
-            {
-              name: 'Test Plugin Config',
-              plugins: {},
-            },
-          ],
         },
         { test1: 'test1', test2: 'test2' },
       ),
     ).toEqual({
-      consumer_groups: [
-        {
-          consumers: [
-            {
-              labels: { test1: 'test1', test2: 'test2' },
-              username: 'Test Nested Consumer',
-            },
-          ],
-          labels: { test1: 'test1', test2: 'test2' },
-          name: 'Test Consumer Group',
-          plugins: {},
-        },
-      ],
       consumers: [
         { labels: { test1: 'test1', test2: 'test2' }, username: 'alice' },
       ],
-      plugin_configs: [
-        {
-          labels: { test1: 'test1', test2: 'test2' },
-          name: 'Test Plugin Config',
-          plugins: {},
-        },
-      ],
       routes: [
         {
           labels: { test1: 'test1', test2: 'test2' },
@@ -131,9 +89,6 @@ describe('CLI utils', () => {
           name: 'Test Stream Route',
         },
       ],
-      upstreams: [
-        { labels: { test1: 'test1', test2: 'test2' }, name: 'Test Upstream' },
-      ],
     });
   });
 
@@ -186,62 +141,17 @@ describe('CLI utils', () => {
               labels: { test: 'test' },
             },
           ],
-          upstreams: [
-            {
-              name: 'Test Upstream',
-              labels: { test: 'test' },
-            },
-          ],
-          consumer_groups: [
-            {
-              name: 'Test Consumer Group',
-              labels: { test: 'test' },
-              plugins: {},
-              consumers: [
-                {
-                  username: 'Test Nested Consumer',
-                  labels: { test: 'test' },
-                },
-              ],
-            },
-          ],
-          plugin_configs: [
-            {
-              name: 'Test Plugin Config',
-              labels: { test: 'test' },
-              plugins: {},
-            },
-          ],
         },
         { test1: 'test1', test2: 'test2' },
       ),
     ).toEqual({
-      consumer_groups: [
-        {
-          consumers: [
-            {
-              labels: { test: 'test', test1: 'test1', test2: 'test2' },
-              username: 'Test Nested Consumer',
-            },
-          ],
-          labels: { test: 'test', test1: 'test1', test2: 'test2' },
-          name: 'Test Consumer Group',
-          plugins: {},
-        },
-      ],
       consumers: [
         {
           labels: { test: 'test', test1: 'test1', test2: 'test2' },
           username: 'alice',
         },
       ],
-      plugin_configs: [
-        {
-          labels: { test: 'test', test1: 'test1', test2: 'test2' },
-          name: 'Test Plugin Config',
-          plugins: {},
-        },
-      ],
+
       routes: [
         {
           labels: { test: 'test', test1: 'test1', test2: 'test2' },
@@ -281,12 +191,6 @@ describe('CLI utils', () => {
           name: 'Test Stream Route',
         },
       ],
-      upstreams: [
-        {
-          labels: { test: 'test', test1: 'test1', test2: 'test2' },
-          name: 'Test Upstream',
-        },
-      ],
     });
   });
 });