https://github.com/ron96g/supertest-docs
A plugin for supertest that can be used to document REST APIs. It is influenced by the Spring-Boot solution restdocs.
https://github.com/ron96g/supertest-docs
automation docs documentation markdown node restdocs supertest unit-testing
Last synced: 6 months ago
JSON representation
A plugin for supertest that can be used to document REST APIs. It is influenced by the Spring-Boot solution restdocs.
- Host: GitHub
- URL: https://github.com/ron96g/supertest-docs
- Owner: ron96G
- Created: 2022-11-22T17:13:32.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2022-11-22T17:15:28.000Z (about 3 years ago)
- Last Synced: 2025-03-27T14:53:37.111Z (10 months ago)
- Topics: automation, docs, documentation, markdown, node, restdocs, supertest, unit-testing
- Language: JavaScript
- Homepage:
- Size: 10.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Supertest Documentation Plugin
A plugin for [supertest](https://github.com/visionmedia/supertest) that can be used to document REST APIs. It is influenced by the Spring-Boot solution [restdocs](https://spring.io/projects/spring-restdocs).
It uses the request/response from the supertest call in a unit-test to generate snippets.
These snippets may then be used to enhance or further generate any documentation.
It may also be used independently of supertest. This could be useful when documenting events where the API is developed by another team and there is no mock in place (see [here](test/document.test.js#L87)).
## Supported Formats
The generated snippets are all in a specific output format. The following formats are supported:
### Markdown
Which could be used with [mkdocs](https://www.mkdocs.org/).
---
## Generated Snippets (Examples)
Currently the following snippets are generated when using supertest in a unit-test.
These were generated using the following unit-test (see [here](test/document.test.js#L38)):
```js
request(url)
.post("/jsonTest")
// name here defines the output directory
.document("requestDocument(json)", {
host: "test.host.com:443",
protocol: "https",
})
.setD("Content-Type", "application/json", "Content-Type must be JSON")
.set("Accept", "application/json")
.send({ name: "john" })
.expect({ hello: "world" }, done);
```
All generated snippets can then be found under `generated-snippets/requestDocument(json)/`.
### Curl Request
```bash
$ curl 'https://test.host.com/jsonTest' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"name":"john"}'
```
### HTTP Request
```
POST /jsonTest HTTP/1.1
Host: test.host.com
Accept-Encoding: gzip, deflate
Content-Type: application/json
Accept: application/json
{
"name": "john"
}
```
### HTTP Response
```
Status-Code: "200 OK"
x-powered-by: Express
content-type: application/json; charset=utf-8
etag: W/"11-IkjuL6CqqtmReFMfkkvwC0sKj04"
{
"hello": "world"
}
```
### Request Body
```json
{
"name": "john"
}
```
### Request Headers
| Name | Description |
| :------------- | :------------------------ |
| `Content-Type` | Content-Type must be JSON |
### Response Body
```json
{
"hello": "world"
}
```
### Response Headers
No relevant information.
---