Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/danielgtaylor/openapi-cli-generator
Generate a CLI from an OpenAPI 3 specification
https://github.com/danielgtaylor/openapi-cli-generator
cli code-generator openapi rest-api rest-client
Last synced: 13 days ago
JSON representation
Generate a CLI from an OpenAPI 3 specification
- Host: GitHub
- URL: https://github.com/danielgtaylor/openapi-cli-generator
- Owner: danielgtaylor
- License: mit
- Created: 2018-09-30T03:27:34.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-10-25T21:22:27.000Z (about 1 year ago)
- Last Synced: 2024-10-04T10:41:53.241Z (about 1 month ago)
- Topics: cli, code-generator, openapi, rest-api, rest-client
- Language: Go
- Size: 225 KB
- Stars: 180
- Watchers: 5
- Forks: 49
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenAPI CLI Generator
[](https://godoc.org/github.com/danielgtaylor/openapi-cli-generator)
[](https://travis-ci.org/danielgtaylor/openapi-cli-generator)
[](https://goreportcard.com/report/github.com/danielgtaylor/openapi-cli-generator)
[](https://github.com/danielgtaylor/openapi-cli-generator/releases)
---
**Note: this project has been superceded by Restish, an advanced auto-configured OpenAPI CLI that just works:**
- https://rest.sh/
- https://github.com/danielgtaylor/restish
---
This project can be used to generate CLIs from OpenAPI 3 specs. The generated CLIs have the following features:
- Authentication support for API keys and [Auth0](https://auth0.com/).
- Commands, subcommands, & flag parsing through [Cobra](https://github.com/spf13/cobra)
- Configuration through [Viper](https://github.com/spf13/viper)
- JSON, YAML, or TOML config files in `/etc/` and `$HOME`, e.g. `{"verbose": true}` in `~/.my-app/config.json`
- From environment: `APP_NAME_VERBOSE=1`
- From flags: `--verbose`
- HTTP middleware through [Gentleman](https://github.com/h2non/gentleman/)
- Command middleware with custom parameters (see customization below)
- Input through `stdin` or [CLI shorthand](https://github.com/danielgtaylor/openapi-cli-generator/tree/master/shorthand)
- Built-in cache to save data between runs
- Fast structured logging via [zerolog](https://github.com/rs/zerolog)
- Pretty output colored by [Chroma](https://github.com/alecthomas/chroma)
- Response filtering & projection by [JMESPath](http://jmespath.org/) plus [enhancements](https://github.com/danielgtaylor/go-jmespath-plus#enhancements)
## Getting Started
First, make sure you have Go installed. Then, you can grab this project:
```sh
$ go get -u github.com/danielgtaylor/openapi-cli-generator
```
Next, make your project directory and generate the commands file.
```sh
# Set up your new project
$ mkdir my-cli && cd my-cli
# Create the default main file. The app name is used for config and env settings.
$ openapi-cli-generator init
# Generate the commands
$ openapi-cli-generator generate openapi.yaml
```
Last, add a line like the following to your `main.go` file:
```go
openapiRegister(false)
```
If you would like to generate a client for many APIs and have each available under their own namespace, pass `true` instead. Next, build your client:
```sh
# Build & install the generated client.
$ go install
# Test it out!
$ my-cli --help
```
## OpenAPI Extensions
Several extensions properties may be used to change the behavior of the CLI.
| Name | Description |
| ------------------- | ------------------------------------------------------------------ |
| `x-cli-aliases` | Sets up command aliases for operations. |
| `x-cli-description` | Provide an alternate description for the CLI. |
| `x-cli-ignore` | Ignore this path, operation, or parameter. |
| `x-cli-hidden` | Hide this path, or operation. |
| `x-cli-name` | Provide an alternate name for the CLI. |
| `x-cli-waiters` | Generate commands/params to wait until a certain state is reached. |
### Aliases
The following example shows how you would set up a command that can be invoked by either `list-items` or simply `ls`:
```yaml
paths:
/items:
get:
operationId: ListItems
x-cli-aliases:
- ls
```
### Description
You can override the default description easily:
```yaml
paths:
/items:
description: Some info talking about HTTP headers.
x-cli-description: Some info talking about command line arguments.
```
### Exclusion
It is possible to exclude paths, operations, and/or parameters from the generated CLI. No code will be generated as they will be completely skipped.
```yaml
paths:
/included:
description: I will get included in the CLI.
/excluded:
x-cli-ignore: true
description: I will not be in the CLI :-(
```
Alternatively, you can have the path or operation exist in the UI but be hidden from the standard help list. Specific help is still available via `my-cli my-hidden-operation --help`:
```yaml
paths:
/hidden:
x-cli-hidden: true
```
### Name
You can override the default name for the API, operations, and params:
```yaml
info:
x-cli-name: foo
paths:
/items:
operationId: myOperation
x-cli-name: my-op
parameters:
- name: id
x-cli-name: item-id
in: query
```
With the above, you would be able to call `my-cli my-op --item-id=12`.
### Waiters
Waiters allow you to declaratively define special commands and parameters that will cause a command to block and wait until a particular condition has been met. This is particularly useful for asyncronous operations. For example, you might submit an order and then wait for that order to have been charged successfully before continuing on.
At a high level, waiters consist of an operation and a set of matchers that select a value and compare it to an expectation. For the example above, you might call the `GetOrder` operation every 30 seconds until the response's JSON `status` field is equal to `charged`. Here is what that would look like in your OpenAPI YAML file:
```yaml
info:
title: Orders API
paths:
/order/{id}:
get:
operationId: GetOrder
description: Get an order's details.
parameters:
- name: id
in: path
responses:
200:
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum: ['placed', 'charged', 'shipped', 'returned']
x-cli-waiters:
order-charged:
delay: 30
attempts: 10
operationId: GetOrder
matchers:
- select: response.body#status
expected: charged
```
The generated CLI will work like this: `my-cli wait order-charged $ID` where `$ID` corresponds to the `GetOrder` operation's `id` parameter. It will try to get and match the status 10 times, with a pause of 30 seconds between tries. If it matches, it will exit with a zero status code. If it fails, it will exit with a non-zero exit code and log a message.
This is a great start, but we can make this a little bit friendlier to use. Take a look at this modified waiter configuration:
```yaml
x-cli-waiters:
order-charged:
short: Short description for CLI `--help`
long: Long description for CLI `--help`
delay: 30
attempts: 10
operationId: GetOrder
matchers:
- select: response.body#status
expected: charged
- select: response.status
expected: 404
state: failure
after:
CreateOrder:
id: response.body#order_id
```
Here we added two new features:
1. A short-circuit to fail fast. If we type an invalid order ID then we want the command to exit immediately with a non-zero exit code.
2. The `after` block allows us to add a parameter to an _existing_ operation to invoke the waiter. This block says that after a call to `CreateOrder` with a `--wait-order-charged` param, it should call the waiter's `GetOrder` operation with the `id` param set to the result of the `response.body#order_id` selector.
You can now create and wait on an order via `my-cli create-order