diff --git a/.gitignore b/.gitignore index 7738f9a..a95d049 100644 --- a/.gitignore +++ b/.gitignore @@ -154,3 +154,5 @@ dist .yarn/install-state.gz .pnp.* + +dist/ diff --git a/docs/docs/cli/installation.md b/docs/docs/cli/installation.md index 25267fe..3fd1687 100644 --- a/docs/docs/cli/installation.md +++ b/docs/docs/cli/installation.md @@ -1 +1,55 @@ # Installation + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +Use brew package manaager +
+
+ +```bash +brew install one-platform/apic +``` + +
+ +We use cloudsmith to distribute packages +
+
+ +```bash +curl -1sLf \ + 'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/cfg/setup/bash.deb.sh' \ + | sudo bash +``` + +
+ +We use cloudsmith to distribute packages +
+
+ +```bash +curl -1sLf \ + 'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/cfg/setup/bash.deb.sh' \ + | sudo bash +``` + +
+
+ +To make sure it's installed correctly you can run + +```bash +apic help +``` + +### Run against an OpenAPI + +Let's run against [petstore api](https://google.com) + +```bash +apic run --schema https://petstore3.swagger.io/api/v3/openapi.json +``` diff --git a/docs/docs/cli/overview.md b/docs/docs/cli/overview.md index 07dd0c5..ec7077e 100644 --- a/docs/docs/cli/overview.md +++ b/docs/docs/cli/overview.md @@ -1 +1,53 @@ # Overview + +CLI is a core component of our whole architecture. It is what takes API Catalog closer to the API developer. + +It mainly validates your API schema file, runs it against the rules you have specified, and then submits the final report to the server. + +## CLI Architecture + +[image-to-be-added-cli-arch] + +### Config + +The config provides options for teams to customize the rule working, disable some rules and add their own rules. It will soon give options for providing other information like API metadata, changelog files, etc. + +The following formats as config file + +1. YAML +2. JSON +3. TOML + +
+A simple config file. + +```yml +rules: + url_plural_checker: + options: + base_urls: + - /api/v1 + url_case_checker: + options: + base_urls: + - /api/v1 + casing: kebabcase +plugins: + rules: + test_plugin: + file: "./my-own-rule/index.js" +``` + +
+ +### Rules + +Rules are the validations executed over a schema file. + +They can be as simple as URL length checks to API performance testing. Each rule will assign a score to one of the API Catalog measured properties and, if any validation fails, will be reported. + +:::info + +For more information on rules [head over to rules section.](/cli/rules/what-are-rules) + +::: diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index f7016fb..1a5248f 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -1 +1,46 @@ # Why API Catalog + +## Background + +API Catalog was launched in Nov 2022 to make API discoverability easier and to give API consumers an easy way to interact with APIs. But later, we saw a new potential in the API Catalog. + +We call it **API Catalog Next**. + +Every team has there own best practices in API. Some document it, and some end up in a discussion. + +But how can we validate and make sure your API quality is maintained? + +Consider a new developer or even a new team. How to ensure that they will follow the practices, thus the end API consumers are happy. + +## Our Aim + +API Catalog aims to give teams and API consumers a **quality of assurance**. It tries to answer a simple question. How good is your API? Think of it like Google Lighthouse but for your APIs. + +It mainly measures three properties that define API quality. + +1. Security +2. Performance +3. Quality/Best Practices + +Best practices always vary around the team. But we have provided you with a very extensible and customizable system so that teams can customize it as they wish. + +Catalog generates scores and reports and provides you with valuable insights like + +1. Recent Activity +2. Score Metrics +3. The number of breaking changes. Give you an idea of how stable an API is. +4. Number of checks +5. And more. + +But this doesn't waver us away from our initial goal. That is making the life of API consumers easier. We will make it even better. The new catalog will soon support + +1. API Changelogs +2. Single source of truth for all API documents +3. Code snippets +4. Status Checks + +:::info + +API Catalog Next is in the **alpha state**. But hold on to your seatbelts because we are moving at light speed. + +::: diff --git a/internal/cli/pluginmanager/plugin_manager.go b/internal/cli/pluginmanager/plugin_manager.go index 83bad51..8af77ef 100644 --- a/internal/cli/pluginmanager/plugin_manager.go +++ b/internal/cli/pluginmanager/plugin_manager.go @@ -67,7 +67,6 @@ func (p *PluginManager) LoadBuiltinPlugin() error { } else { homeDir, _ := os.UserHomeDir() path = filepath.Clean(filepath.Join(homeDir, fmt.Sprintf(".apic/plugins/builtin/%s", p.ApiType))) - } builtInPlugin, err := os.ReadDir(path) diff --git a/internal/cli/run.go b/internal/cli/run.go index 8f76130..181cddb 100644 --- a/internal/cli/run.go +++ b/internal/cli/run.go @@ -58,7 +58,7 @@ func bootUpChecks(fr *filereader.FileReader, logger *CliLogger) { // else download the file logger.Info("Outdated or missing builtin plugin. Installing latest one...") - builtInZipfile, err := fr.ReadIntoRawBytes("./plugins/builtin.zip") + builtInZipfile, err := fr.ReadIntoRawBytes("https://github.com/1-Platform/api-catalog/raw/main/plugins/builtin.zip") if err != nil { log.Fatal(err) }