-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(docs): added content on cli and overall overview
- Loading branch information
Showing
6 changed files
with
154 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -154,3 +154,5 @@ dist | |
.yarn/install-state.gz | ||
.pnp.* | ||
|
||
|
||
dist/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,55 @@ | ||
# Installation | ||
|
||
import Tabs from '@theme/Tabs'; | ||
import TabItem from '@theme/TabItem'; | ||
|
||
<Tabs> | ||
<TabItem value="mac" label="MacOS" default> | ||
Use <a>brew</a> package manaager | ||
<br/> | ||
<br/> | ||
|
||
```bash | ||
brew install one-platform/apic | ||
``` | ||
|
||
</TabItem> | ||
<TabItem value="alpine" label="Alpine" > | ||
We use cloudsmith to distribute packages | ||
<br/> | ||
<br/> | ||
|
||
```bash | ||
curl -1sLf \ | ||
'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/cfg/setup/bash.deb.sh' \ | ||
| sudo bash | ||
``` | ||
|
||
</TabItem> | ||
<TabItem value="deb" label="Debian/Ubuntu"> | ||
We use cloudsmith to distribute packages | ||
<br/> | ||
<br/> | ||
|
||
```bash | ||
curl -1sLf \ | ||
'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/cfg/setup/bash.deb.sh' \ | ||
| sudo bash | ||
``` | ||
|
||
</TabItem> | ||
</Tabs> | ||
|
||
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 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
|
||
<details> | ||
<summary>A simple config file.</summary> | ||
|
||
```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" | ||
``` | ||
</details> | ||
### 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) | ||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters