Skip to content

Commit

Permalink
closes #35
Browse files Browse the repository at this point in the history
  • Loading branch information
@gdereese
gdereese committed Mar 11, 2018
1 parent 6172985 commit dfb074b
Showing 1 changed file with 6 additions and 106 deletions.
112 changes: 6 additions & 106 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,13 @@ This package has been tested on the following versions of Node.js:

## Installation

### Install locally
### Install locally:

```
npm install vorpal-openapi
```

### Install globally
### Install globally:

```
npm install vorpal-openapi -g
Expand Down Expand Up @@ -91,108 +91,8 @@ axios.get('http://url/to/swagger.json').then(function(response) {
});
```

## Commands
## Further Reading

### API Operations

Each API operation defined in the specification is given its own distinct command in the CLI. The `operationId` property value is used as the name of the command.

#### Operation Grouping

If the `operations.groupBy` option is set to something other than `none`, the operations are grouped as follows:

Example spec:

```javascript
{
...
"paths": {
"/widget": {
"post": {
"operationId": "addWidget",
"tags": ["admin"]
...
},
"get": {
"operationId": "getWidgets",
"tags": ["reporting"]
...
}
},
"/whizbang": {
"update": {
"operationId": "updateWhizbang",
"tags": ["admin"]
}
}
}
...
}
```

| `operations.groupBy` | Generated Commands |
| :------------------- | :---------------------------------------------------------------------------- |
| `none` | `add-widget`<br />`get-widgets`<br />`update-whizbang` |
| `path` | `widget add-widget`<br />`widget get-widgets`<br />`whizbang update-whizbang` |
| `tag` | `admin add-widget`<br />`admin update-whizbang`<br />`widget get-widgets` |

When operations are grouped, you can type `help <group-name>` to get a listing of all commands in that group.

Also, grouped operations will have an alias of their operation ID so that they can be invoked without having to specify the group name as well. In the example below, either command line will invoke the same command:

```
swagger-petstore$ pet get-pet-by-id 1
```

```
swagger-petstore$ get-pet-by-id 1
```

#### Parameters

Each parameter defined in the operation's `parameters` object is mapped to an operation parameter in the CLI. They are handled as they are defined in the spec; parameters where `required = true` are required for the command to be executed, all others are optional.

If a body parameter is defined for the operation, it is possible to read the contents of a file directly the request body by specifying the path to the file prepended with the string `file@`:

```
swagger-petstore$ pet add-pet file@path/to/file
```

#### Options

Each API operation command has the following options to configure additional aspects of the request made by the command:

| Option | Description |
| :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--request-content-type` | Indicates the content type of the request body. Available options are taken from those listed in the operation spec's `consumes` object. |
| `--response-content-type` | Indicates the desired content type of the response to be returned. Available options are taken from those listed in the operation spec's `produces` object. |
| `--to-file` | Writes the operation's response body to a file. This option is only available if the operation specifies one or more response content types in the `produces` object. |

### Global Commands

The following commands are added to the CLI by default:

| Command | Description |
| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `about` | Displays information about the API. This command displays various bits from the `info` object of the spec to the user such as the `version`, `contact` and `termsOfService` properties. |
| `clear-auth` | Clears the auth value(s) for the specified authorization scheme. |
| `set-auth` | Sets the value(s) required to fulfill a given authorization scheme accepted/required by the API. A `set-auth` sub-command is created for each scheme defined in the spec's `securityDefinitions` object. You can type `help set-auth` at the CLI prompt to list the schemes available to use. |
| `exit` | Exits the current CLI session and returns to the host command prompt. |
| `help` | Lists each command available in the CLI with a brief description of each. The usage pattern, required and optional parameters, and security requirements are also specified for each command. |

## Options

When utilizing this package as a vorpal extension, an options object can be passed in the `vorpal.use()` function call for customizing the look and behavior of the generated CLI. The schemas for the options object is as follows:

### `options`

| Property | Type | Description |
| :----------- | :------: | :------------------------------------------------------------------------------------------------------------------------------ |
| `operations` | `object` | Options for how operations defined in the OpenAPI/Swagger spec are handled. See [operations](README.md#operations) for details. |
| `spec` | `object` | **(required)** OpenAPI/Swagger specification object. |

### `operations`

| Property | Type | Description |
| :-------- | :------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groupBy` | `string` | Indicates how operations defined in the spec will be grouped. `none` = no grouping, `path` = group by first path segment, `tag` = group by operation tags. |
* [API Operations](https://github.com/gdereese/vorpal-openapi/wiki/API-Operations)
* [Global Commands](https://github.com/gdereese/vorpal-openapi/wiki/Global-Commands)
* [Extension Options](https://github.com/gdereese/vorpal-openapi/wiki/Extension-Options)

0 comments on commit dfb074b

Please sign in to comment.