From 4a46025926986d2aecac24f96e8470e94f46116c Mon Sep 17 00:00:00 2001 From: Lucas Pickering Date: Tue, 24 Oct 2023 19:54:20 -0400 Subject: [PATCH] Add API reference to docs --- README.md | 2 +- docs/src/SUMMARY.md | 15 +++++- docs/src/api/chain.md | 35 ++++++++++++++ docs/src/api/chain_source.md | 23 +++++++++ docs/src/api/profile.md | 21 ++++++++ docs/src/api/request_collection.md | 78 ++++++++++++++++++++++++++++++ docs/src/api/request_recipe.md | 34 +++++++++++++ docs/src/api/template_string.md | 34 +++++++++++++ docs/src/user_guide.md | 1 + src/config/mod.rs | 1 + 10 files changed, 242 insertions(+), 2 deletions(-) create mode 100644 docs/src/api/chain.md create mode 100644 docs/src/api/chain_source.md create mode 100644 docs/src/api/profile.md create mode 100644 docs/src/api/request_collection.md create mode 100644 docs/src/api/request_recipe.md create mode 100644 docs/src/api/template_string.md create mode 100644 docs/src/user_guide.md diff --git a/README.md b/README.md index cfe91671..9bc516cc 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Slumber is a TUI (terminal user interface) REST client. Define, execute, and share configurable HTTP requests. -## Example +## Examples Slumber is based around **collections**. A collection is a group of request **recipes**, which are templates for the requests you want to run. A simple collection could be: diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index d53477ce..e0784e37 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,3 +1,16 @@ # Summary -- [Quick Start](./quick_start.md) +[Quick Start](./quick_start.md) + +# User Guide + +- [User Guide](./user_guide.md) + +# API Reference + +- [Request Collection](./api/request_collection.md) + - [Profile](./api/profile.md) + - [Request Recipe](./api/request_recipe.md) + - [Chain](./api/chain.md) + - [Chain Source](./api/chain_source.md) + - [Template String](./api/template_string.md) diff --git a/docs/src/api/chain.md b/docs/src/api/chain.md new file mode 100644 index 00000000..a7cb05d9 --- /dev/null +++ b/docs/src/api/chain.md @@ -0,0 +1,35 @@ +# Chain + +A chain is a intermediate data type to enable complex template values. Chains enable complex value sources and additional customization, such as much values as sensitive to be masked in the UI. + +To use a chain in a template string, reference it as `{{chains.}}`. + +## Fields + +| Field | Type | Description | Default | +| ----------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------- | -------- | +| `id` | `string` | Unique identifier for this chain | Required | +| `source` | [`ChainSource`](./chain_source.md) | Source of the chained value | Required | +| `sensitive` | `boolean` | Should the value be hidden in the UI? | `false` | +| `selector` | [`JSONPath`](https://www.ietf.org/archive/id/draft-goessner-dispatch-jsonpath-00.html) | Selector to narrow down results in a chained JSON value | `null` | + +See the [`ChainSource`](./chain_source.md) docs for more detail. + +## Examples + +```yaml +# Load chained value from a file +id: username +source: !file ./username.txt +--- +# Prompt the user for a value whenever the request is made +id: password +source: !prompt Enter Password +sensitive: true +--- +# Use a value from another response +# Assume the request recipe with ID `login` returns a body like `{"token": "foo"}` +id: auth_token +source: !request login +selector: $.token +``` diff --git a/docs/src/api/chain_source.md b/docs/src/api/chain_source.md new file mode 100644 index 00000000..ba11cff8 --- /dev/null +++ b/docs/src/api/chain_source.md @@ -0,0 +1,23 @@ +# Chain Source + +A chain source defines how a [Chain](./chain.md) gets its value. It populates the `source` field of a chain. There are multiple source types, and the type is specified using [YAML's tag syntax](https://yaml.org/spec/1.2.2/#24-tags). + +## Types + +| Type | Value | Chained Value | +| --------- | ------------------------------------ | --------------------------------------------------------------- | +| `request` | Request Recipe ID | Body of the most recent response for a specific request recipe. | +| `file` | Path (relative to current directory) | Contents of the file | +| `prompt` | Descriptive prompt for the user | Value entered by the user | + +## Examples + +See the [`Chain`](./chain.md) docs for more holistic examples. + +```yaml +!request login +--- +!file ./username.txt +--- +!prompt Enter Password +``` diff --git a/docs/src/api/profile.md b/docs/src/api/profile.md new file mode 100644 index 00000000..f17445f4 --- /dev/null +++ b/docs/src/api/profile.md @@ -0,0 +1,21 @@ +# Profile + +A profile is a collection of static template values. It's useful for configuring and switching between multiple different environments/settings/etc. + +## Fields + +| Field | Type | Description | Default | +| ------ | ------------------------- | ------------------------------------- | ------------- | +| `id` | `string` | Unique identifier for this profile | Required | +| `name` | `string` | Descriptive name to use in the UI | Value of `id` | +| `data` | `mapping[string, string]` | Fields, mapped to their static values | `{}` | + +## Examples + +```yaml +id: local +name: Local +data: + host: http://localhost:5000 + user_guid: abc123 +``` diff --git a/docs/src/api/request_collection.md b/docs/src/api/request_collection.md new file mode 100644 index 00000000..7b54709c --- /dev/null +++ b/docs/src/api/request_collection.md @@ -0,0 +1,78 @@ +# Request Collection + +The request collection is the primary configuration for Slumber. It defines which requests can be made, and how to make them. When running a `slumber` instance, a single collection file is loaded. If you want to work with multiple collections at once, you'll have to run multiple instances of Slumber. + +## Format & Loading + +A collection is defined as a [YAML](https://yaml.org/) file. When you run `slumber`, it will search the current directory for the following default collection files, in order: + +- `slumber.yml` +- `slumber.yaml` +- `.slumber.yml` +- `.slumber.yaml` + +Whichever of those files is found _first_ will be used. If you want to use a different file for your collection (e.g. if you want to store multiple collections in the same directory), you can override the auto-search with the `--collection` (or `-c`) command line argument. E.g.: + +```sh +slumber -c my-collection.yml +``` + +## Fields + +A request collection supports the following top-level fields: + +| Field | Type | Description | Default | +| ---------- | -------------------------------------------- | ------------------------- | ------- | +| `profiles` | [`list[Profile]`](./profile.md) | Static template values | [] | +| `requests` | [`list[RequestRecipe]`](./request_recipe.md) | Requests Slumber can send | [] | +| `chains` | [`list[Chain]`](./chain.md) | Complex template values | [] | + +## Examples + +```yaml +profiles: + - id: local + name: Local + data: + host: http://localhost:5000 + user_guid: abc123 + - id: prd + name: Production + data: + host: https://httpbin.org + user_guid: abc123 + +chains: + - id: username + source: !file ./username.txt + - id: password + source: !prompt Password + sensitive: true + - id: auth_token + source: !request login + selector: $.token + +# Use YAML anchors for de-duplication +base: &base + headers: + Accept: application/json + Content-Type: application/json + +requests: + - <<: *base + id: login + method: POST + url: "{{host}}/anything/login" + body: | + { + "username": "{{chains.username}}", + "password": "{{chains.password}}" + } + + - <<: *base + id: Get User + method: GET + url: "{{host}}/anything/current-user" + query: + auth: "{{chains.auth_token}}" +``` diff --git a/docs/src/api/request_recipe.md b/docs/src/api/request_recipe.md new file mode 100644 index 00000000..33bdd755 --- /dev/null +++ b/docs/src/api/request_recipe.md @@ -0,0 +1,34 @@ +# Request Recipe + +A request recipe defines how to make a particular request. For a REST API, you'll typically create one request recipe per endpoint. + +## Fields + +| Field | Type | Description | Default | +| --------- | --------------------------------------------------------- | --------------------------------- | ------------- | +| `id` | `string` | Unique identifier for this recipe | Required | +| `name` | `string` | Descriptive name to use in the UI | Value of `id` | +| `method` | [`TemplateString`](./template_string.md) | HTTP request method | Required | +| `url` | [`TemplateString`](./template_string.md) | HTTP request URL | Required | +| `query` | [`mapping[string, TemplateString]`](./template_string.md) | HTTP request query parameters | `{}` | +| `headers` | [`mapping[string, TemplateString]`](./template_string.md) | HTTP request headers | `{}` | +| `body` | [`TemplateString`](./template_string.md) | HTTP request body | `null` | + +## Examples + +```yaml +id: login +name: Login +method: POST +url: "{{host}}/anything/login" +headers: + accept: application/json + content-type: application/json +query: + root_access: yes_please +body: | + { + "username": "{{chains.username}}", + "password": "{{chains.password}}" + } +``` diff --git a/docs/src/api/template_string.md b/docs/src/api/template_string.md new file mode 100644 index 00000000..c872535d --- /dev/null +++ b/docs/src/api/template_string.md @@ -0,0 +1,34 @@ +# Template String + +A template string is represented in YAML as a normal string, and thus supports [all of YAML's string syntaxes](https://www.educative.io/answers/how-to-represent-strings-in-yaml). Template strings receive post-processing that injects dynamic values into the string. A templated value is represented with `{{ }}`. + +Template strings can generally be used in any _value_ in a request recipe (_not_ in keys). They _cannot_ be used in profiles or chains, to avoid the potential for recursive templating. + +## Template Sources + +There are several ways of sourcing templating values: + +| Source | Syntax | Description | +| ----------------------------- | --------------------- | ---------------------------------------------- | +| [Profile](./profile.md) Field | `{{field_name}}` | Static value from a profile | +| Environment Variable | `{{env.VARIABLE}}` | Environment variable from parent shell/process | +| [Chain](./chain.md) | `{{chains.chain_id}}` | Complex chained value | + +## Examples + +```yaml +# Profile value +"hello, {{location}}" +--- +# Multiple dynamic values +"{{greeting}}, {{location}}" +--- +# Environment variable +"hello, {{env.LOCATION}}" +--- +# Chained value +"hello, {{chains.where_am_i}}" +--- +# No dynamic values +"hello, world!" +``` diff --git a/docs/src/user_guide.md b/docs/src/user_guide.md new file mode 100644 index 00000000..cd3d4522 --- /dev/null +++ b/docs/src/user_guide.md @@ -0,0 +1 @@ +# User Guide diff --git a/src/config/mod.rs b/src/config/mod.rs index 9175d40c..167104ea 100644 --- a/src/config/mod.rs +++ b/src/config/mod.rs @@ -106,6 +106,7 @@ pub struct Chain { #[serde(default)] pub sensitive: bool, /// JSONpath to extract a value from the response. For JSON data only. + // TODO strong typing on this pub selector: Option, }