Skip to content

Commit 84b2d0b

Browse files
toumorokoshitoumorokoshi
committed
docs: adding a basic user guide and readme
Adding more information on the user guide and readme, to help explain how to use aepcli.
1 parent a51c34e commit 84b2d0b

2 files changed

Lines changed: 255 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,38 @@
11
# aepcli
2-
A command-line interface of AEP-compliant APIs.
32

4-
## Design
3+
A dynamically generated command-line interface for AEP-compliant APIs.
54

6-
Aepcli reads an OpenAPI definition, published at a path `/openapi.json`. From
7-
this definition, resources are read in, and the standards methods they expose.
5+
## What is aepcli?
6+
7+
aepcli is a command line interface that is able to dynamically generate a CLI
8+
based on OpenAPI definitions for APIs which adhere to the
9+
[aeps](https://aep.dev).
10+
11+
For example, if an OpenAPI definition at `./bookstore.yaml` defines a resource
12+
"Book", that contains create, get, update, and delete methods, aepcli will
13+
generate the commands `aepcli ./bookstore books create`, `aepcli ./bookstore
14+
books get`, `aepcli ./bookstore books update`, and `aepcli ./bookstore delete`.
15+
16+
A config file can also be authored, which allows you to use a nice alias instead,
17+
making your command line look a bit more official:
18+
19+
`aepcli bookstore books create peter-pan --title="Peter Pan"`.
20+
21+
It is useful for the following reasons:
22+
23+
- It provides a highly functional CLI without the need to manually write one
24+
yourself.
25+
- Since the definitions are all openapi files, they can be easily shared and
26+
reused. An update for your command-line interface is just copying an openapi
27+
file (and any relevant configuration).
28+
- Since the schema is separate from the binary, new commands can be added
29+
without having to update the binary, and new binary updates can happen without
30+
modifying the schema.
831

932
## Usage Guide
1033

34+
For a more complete guide, see the [user guide](docs/userguide.md).
35+
1136
### All commands
1237

1338
All commands require the address of the host they are requesting. Therefore all

‎docs/userguide.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# User Guide
2+
3+
## Installation
4+
5+
To install the binary, you can download it from the [releases page](https://github.com/aep-dev/aepcli/releases).
6+
7+
Alternatively, you can install it using `go install github.com/aep-dev/aepcli/cmd/aepcli@latest`.
8+
9+
## Getting started
10+
11+
To get started with aepcli, you will need an OpenAPI definition for the API you
12+
want to interact with, remotely via a URL, or locally in a file.
13+
14+
From there, see what resources aepcli can find:
15+
16+
```bash
17+
aepcli https://bookstore.example.com/openapi.json --help
18+
Usage: [resource] [method] [flags]
19+
20+
Command group for http://localhost:8081
21+
22+
Available resources:
23+
- book
24+
- book-edition
25+
- isbn
26+
- publisher
27+
```
28+
29+
If a resource is missing that you expect, increase the verbosity of the
30+
logs to see what the parser has done:
31+
32+
```bash
33+
aepcli --log-level=debug https://bookstore.example.com/openapi.json
34+
2024/11/02 06:13:33 DEBUG parsing openapi pathPrefix=""
35+
2024/11/02 06:13:33 DEBUG path path=/publishers/{publisher}/books/{book}/editions
36+
2024/11/02 06:13:33 DEBUG parsing path for resource path=/publishers/{publisher}/books/{book}/editions
37+
2024/11/02 06:13:33 DEBUG path path=/publishers/{publisher}/books/{book}/editions/{book-edition}
38+
```
39+
40+
Select a resource to see what commands are available:
41+
42+
### Resource-level commands
43+
44+
At the resource level, the following commands are available if the API supports
45+
them:
46+
47+
- `list`
48+
- `get`
49+
- `create`
50+
- `update`
51+
- `delete`
52+
53+
For example, to see the commands available for the `book` resource:
54+
55+
```bash
56+
aepcli bookstore book
57+
Usage:
58+
book [command]
59+
60+
Available Commands:
61+
completion Generate the autocompletion script for the specified shell
62+
create Create a book
63+
delete Delete a book
64+
get Get a book
65+
help Help about any command
66+
list List book
67+
update Update a book
68+
69+
Flags:
70+
-h, --help help for book
71+
--publisher string The publisher of the resource
72+
73+
Use "book [command] --help" for more information about a command.
74+
```
75+
76+
For commands that operate on a specific resoure, a positional argument for the
77+
resource id is required:
78+
79+
```bash
80+
aepcli bookstore book get 123
81+
```
82+
83+
note that for the create operation, resources [may not support specifying
84+
the resource id]().
85+
86+
### Using configuration files
87+
88+
aepcli supports api configurations, which provide a semantic name for the api.
89+
90+
To add a configuration, add the following to your `$HOME/.config/aepcli/config.toml` file:
91+
92+
```toml
93+
[apis.bookstore]
94+
openapi = "openapis/bookstore.json"
95+
# specify pathprefix if there is a common path prefix for all resources,
96+
# that are not part of the resource pattern.
97+
pathprefix = "/bookstore"
98+
# specify serverurl to override the server URL,
99+
# or to set one if it is not present in the openapi definition.
100+
serverurl = "https://bookstore.example.com"
101+
# specify headers as comma-separated key=value pairs
102+
headers = ["X-API-TOKEN=123", "X-API-CLIENT=aepcli"]
103+
```
104+
105+
If you would like to use aepcli as your recommend command-line interface for
106+
your API, you can provide a simple script to write the appropriate configuration
107+
to your configuration file.
108+
109+
### specifying resource parent ids
110+
111+
Some resources are nested, and require ids of each parent to be specified. For
112+
example, a book-edition has a book for a parent, which may in turn have a
113+
publisher as a parent:
114+
115+
```
116+
/publishers/{publisher}/books/{book}/editions/{book-edition}
117+
```
118+
119+
In this case, the pattern id names (which should be the resource singular) are
120+
used as the parent flags:
121+
122+
```bash
123+
aepcli bookstore book-edition --book peter-pan --publisher consistent-house get 2
124+
```
125+
126+
*note*: parent ids must come before the verb, and are indicated in the help
127+
text:
128+
129+
```bash
130+
Usage:
131+
book-edition [command]
132+
133+
Available Commands:
134+
completion Generate the autocompletion script for the specified shell
135+
create Create a book-edition
136+
delete Delete a book-edition
137+
get Get a book-edition
138+
help Help about any command
139+
list List book-edition
140+
141+
Flags:
142+
--book string The book of the resource
143+
-h, --help help for book-edition
144+
--publisher string The publisher of the resource
145+
146+
Use "book-edition [command] --help" for more information about a command
147+
```
148+
149+
### Mutation flags
150+
151+
top-level fields for a resource are converted into keyword arguments:
152+
153+
```bash
154+
aepcli bookstore book create --title "Peter Pan" --publisher "consistent-house"
155+
```
156+
157+
nested objects are currently specified as an object (this may change based on
158+
user feedback, pre-1.0):
159+
160+
```bash
161+
aepcli bookstore book-edition create --book "peter-pan" --publisher "consistent-house" --metadata '{"format": "hardback"}'
162+
```
163+
164+
lists are specified as a comma-separated list:
165+
166+
```bash
167+
aepcli bookstore book-edition create --book "peter-pan" --publisher "consistent-house" --tags "fantasy,childrens"
168+
```
169+
170+
## OpenAPI Definitions
171+
172+
### OAS definitions supported
173+
174+
oas definitions must have the following to be usable:
175+
176+
- The path in the openapi path must adhere to [aep pattern rules](https://aep.dev/4/#annotating-resource-types):
177+
178+
```yaml
179+
paths:
180+
"projects/{project}/user-events/{user-event}":
181+
```
182+
183+
- Each operation on a resource must use an oas schema reference:
184+
185+
```yaml
186+
# ...
187+
paths:
188+
/widgets:
189+
get:
190+
responses:
191+
'200':
192+
content:
193+
application/json:
194+
schema:
195+
$ref: '#/components/schemas/widget'
196+
```
197+
198+
- Each schema for a resource must use an aep-compliant resource singular as it's name.
199+
200+
```yaml
201+
# ...
202+
components:
203+
schemas:
204+
widget:
205+
# ...
206+
```
207+
208+
aepcli will attempt to find your resources via the following method:
209+
210+
1. Iterate through all of the paths, usingthe path as the resource pattern.
211+
2. Extract the schemas from the components section.
212+
213+
### OAS versions Supported
214+
215+
aepcli supports OpenAPI 3.1.0, but does try to provide best-effort support for
216+
OpenAPI 2.0.
217+
218+
## AEP deviations supported
219+
220+
aepcli provides limited support for deviations from the OpenAPI specification. The following deviations are supported, although more may be supported but not documented:
221+
222+
- List APIs whose response schema do not use the field "results" for containing
223+
the results - any field name can be used.
224+
- Using PascalCase for the schema name. This is converted, best effort, to
225+
kebab-case when used in the command group. Switching to kebab-case is
226+
recommended.

0 commit comments

Comments
 (0)