# curldoc

> Executable Web API document format using the curl command

Latest version **0.0.2** (published 2021-07-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install curldoc
pnpm add curldoc
yarn add curldoc
bun add curldoc
```

Provides the command `curldoc`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.2 |
| Published | 2021-07-20 |
| First published | 2021-07-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 44.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Keisuke Nakayama |
| Maintainers | basd4g |
| Keywords | curl, document, http, markdown, mock, server |

## Links

- npm: https://www.npmjs.com/package/curldoc
- Repository: https://github.com/yammerjp/curldoc
- Homepage: https://github.com/yammerjp/curldoc#readme
- Issues: https://github.com/yammerjp/curldoc/issues
- npm.io page: https://npm.io/package/curldoc

## Dependencies (2)

- [shlex](https://npm.io/package/shlex.md) ^2.1.0
- [remark](https://npm.io/package/remark.md) ^13.0.0

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 0.0.2 (latest) — 2021-07-20
- 0.0.1 — 2021-07-20

## README

# curldoc

curldoc is a simple executable Web API document format using the curl command.

The CLI Application of curldoc behave a HTTP mock server from a markdown file of Web API document.

You can create a mock server with such as the following markdown document.

<pre>

The document is a markdown file.
You can write anything outside of ``` ... ```

And you can describe a mock server's endpoint behaviors with a pair of code-block 'curldoc-request' and 'curldoc-response'.

First, please describe accepting reqeust with curl command format in 'curldoc-request'

```curldoc-request
curl http://localhost:3000/hello --header 'Accept: application/json'
```

Next, please describe returning response body text in 'curldoc-request'
(HTTP status code is '200 OK'.)

```curldoc-response
{
    "message": "hello",
    "path": "/json_endpoint"
}
```

In addition, you can specify any HTTP response headers or HTTP status code with using a code-block 'curldoc-response-include'

```curldoc-request
curl http://localhost:3000/response-internal-server-error
```

```curldoc-response-include
HTTP/1.1 500 Internal Server Error
Content-Type: text/plain
Transfer-Encoding: chunked

Internal Server Error....


```

</pre>

## Usage

### CLI



```sh
# Install CLI-app
$ npm install --global curldoc

# Download sample document
$ curl -sL https://raw.githubusercontent.com/yammerjp/curldoc/main/example/helloworld.md > helloworld.md

# Start mock server
$ curldoc helloworld.md

# Usage:
# $ curldoc (--port <TCP port>) <markdown file paths ... >
```

### Library

1. Install the npm package 'curldoc' with `npm i curldoc` for your project
2. Create API document ([example](./example/helloworld.md))
3. Write TypeScript/JavaScript such as the following code

```typescript
import curldoc from 'curldoc'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

async function main() {
  const server = await curldoc.server(3000, [ 'path/to/markdown/file.md' ])

  await wait(1000)

  server.close()
  console.log('closed')
}

main()
```

## Support curl options

You can use following the options in a markdown's codeblock 'curldoc-request'.

- `--header`, `-H` ... specify http request headers
- `--data-raw` ... specify a http request body
- `--request`, `-X` ... specify a http request method

If you want to use other options, please contribute to the repository.
(curl options are processed in /src/documentProcessor/curlOptionHandlers.ts)

## LICENSE

MIT

---
_Source: https://npm.io/package/curldoc · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._