Skip to content

Commit 07a99a1

Browse files
LexLuengasLexLuengas
committed
docs: extend Usage section in README
1 parent 4e63a11 commit 07a99a1

File tree

1 file changed

+111
-86
lines changed

1 file changed

+111
-86
lines changed

‎README.md‎

Lines changed: 111 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,36 @@ The idea is to place the proxy between a client (e.g. a frontend app) and a web
2121
</picture>
2222
</p>
2323

24+
## Requirements
25+
26+
We run all tests with Node.js versions 10 and 12. Higher versions could possibly work but are not currently
27+
supported.
28+
2429
## Installation
2530

26-
Do `npm install -g openapi-cop`, or `npm install openapi-cop` to install locally.
31+
To install the CLI globally:
32+
```npm install -g openapi-cop```
33+
34+
To install the package locally (inside an existing NPM package) and run the proxy programatically:
35+
```npm install openapi-cop```
36+
37+
We also publish a Docker image [lxlu/openapi-cop](https://hub.docker.com/r/lxlu/openapi-cop) that you can use for your
38+
convenience. This means you can also run openapi-cop with
39+
something like
40+
```docker run --rm -p 8888:8888 lxlu/openapi-cop```
41+
42+
## Usage
43+
44+
There are three ways to run openapi-cop:
2745

28-
## CLI Usage
46+
1. Start it with the CLI.
47+
2. Run it programatically inside Node.js.
48+
3. Start a container based on the Docker image.
2949

30-
The *openapi-cop* node package installs itself as an executable linked as `openapi-cop`. Run the command with the `--help` flag to get information about the CLI:
50+
### CLI Usage
51+
52+
The *openapi-cop* node package installs itself as an executable linked as `openapi-cop`. Run the command with
53+
the `--help` flag to get information about the CLI:
3154

3255
```txt
3356
Usage: openapi-cop [options]
@@ -46,92 +69,93 @@ Options:
4669
-h, --help output usage information
4770
```
4871

49-
The proxy validates the requests and responses in the communication with a target server. By default, the proxy will respond with a 500 status code when the validation fails.
72+
The proxy validates the requests and responses in the communication with a target server. By default, the proxy will
73+
respond with a 500 status code when the validation fails.
5074

5175
<details><summary>Sample validation failure response</summary>
5276

5377
```json
5478
{
55-
"error": {
56-
"message": "openapi-cop Proxy validation failed",
57-
"request": {
58-
"method": "POST",
59-
"path": "/pets",
60-
"headers": {
61-
"host": "localhost:8888",
62-
"user-agent": "curl/7.59.0",
63-
"accept": "*/*",
64-
"content-type": "application/json",
65-
"content-length": "16"
66-
},
67-
"query": {},
68-
"body": {
69-
"data": "sent"
70-
}
71-
},
72-
"response": {
73-
"statusCode": 201,
74-
"body": "{}",
75-
"headers": {
76-
"x-powered-by": "Express",
77-
"openapi-cop-openapi-file": "7-petstore.yaml",
78-
"content-type": "application/json; charset=utf-8",
79-
"content-length": "2",
80-
"etag": "W/\"2-vyGp6PvFo4RvsFtPoIWeCReyIC8\"",
81-
"date": "Thu, 25 Jul 2019 13:39:58 GMT",
82-
"connection": "close"
83-
},
84-
"request": {
85-
"uri": {
86-
"protocol": "http:",
87-
"slashes": true,
88-
"auth": null,
89-
"host": "localhost:8889",
90-
"port": "8889",
91-
"hostname": "localhost",
92-
"hash": null,
93-
"search": null,
94-
"query": null,
95-
"pathname": "/pets",
96-
"path": "/pets",
97-
"href": "http://localhost:8889/pets"
98-
},
99-
"method": "POST",
100-
"headers": {
101-
"host": "localhost:8888",
102-
"user-agent": "curl/7.59.0",
103-
"accept": "*/*",
104-
"content-type": "application/json",
105-
"content-length": "16",
106-
"accept-encoding": "gzip, deflate"
107-
}
108-
}
79+
"error": {
80+
"message": "openapi-cop Proxy validation failed",
81+
"request": {
82+
"method": "POST",
83+
"path": "/pets",
84+
"headers": {
85+
"host": "localhost:8888",
86+
"user-agent": "curl/7.59.0",
87+
"accept": "*/*",
88+
"content-type": "application/json",
89+
"content-length": "16"
90+
},
91+
"query": {},
92+
"body": {
93+
"data": "sent"
94+
}
95+
},
96+
"response": {
97+
"statusCode": 201,
98+
"body": "{}",
99+
"headers": {
100+
"x-powered-by": "Express",
101+
"openapi-cop-openapi-file": "7-petstore.yaml",
102+
"content-type": "application/json; charset=utf-8",
103+
"content-length": "2",
104+
"etag": "W/\"2-vyGp6PvFo4RvsFtPoIWeCReyIC8\"",
105+
"date": "Thu, 25 Jul 2019 13:39:58 GMT",
106+
"connection": "close"
107+
},
108+
"request": {
109+
"uri": {
110+
"protocol": "http:",
111+
"slashes": true,
112+
"auth": null,
113+
"host": "localhost:8889",
114+
"port": "8889",
115+
"hostname": "localhost",
116+
"hash": null,
117+
"search": null,
118+
"query": null,
119+
"pathname": "/pets",
120+
"path": "/pets",
121+
"href": "http://localhost:8889/pets"
109122
},
110-
"validationResults": {
111-
"request": {
112-
"valid": true,
113-
"errors": null
114-
},
115-
"response": {
116-
"valid": false,
117-
"errors": [
118-
{
119-
"keyword": "required",
120-
"dataPath": "",
121-
"schemaPath": "#/required",
122-
"params": {
123-
"missingProperty": "code"
124-
},
125-
"message": "should have required property 'code'"
126-
}
127-
]
128-
},
129-
"responseHeaders": {
130-
"valid": true,
131-
"errors": null
132-
}
123+
"method": "POST",
124+
"headers": {
125+
"host": "localhost:8888",
126+
"user-agent": "curl/7.59.0",
127+
"accept": "*/*",
128+
"content-type": "application/json",
129+
"content-length": "16",
130+
"accept-encoding": "gzip, deflate"
133131
}
132+
}
133+
},
134+
"validationResults": {
135+
"request": {
136+
"valid": true,
137+
"errors": null
138+
},
139+
"response": {
140+
"valid": false,
141+
"errors": [
142+
{
143+
"keyword": "required",
144+
"dataPath": "",
145+
"schemaPath": "#/required",
146+
"params": {
147+
"missingProperty": "code"
148+
},
149+
"message": "should have required property 'code'"
150+
}
151+
]
152+
},
153+
"responseHeaders": {
154+
"valid": true,
155+
"errors": null
156+
}
134157
}
158+
}
135159
}
136160
```
137161

@@ -160,7 +184,7 @@ Two headers are added to the response:
160184
```
161185

162186
</details>
163-
187+
164188
- `openapi-cop-source-request`: contains a simplified version of the original request sent by the client as JSON.
165189

166190
<details><summary>Interface</summary>
@@ -181,11 +205,13 @@ Two headers are added to the response:
181205

182206
</details>
183207

184-
See the references of [OpenAPI Backend](https://github.com/anttiviljami/openapi-backend/blob/master/DOCS.md) and [Ajv](https://ajv.js.org/) for more information.
208+
See the references of [OpenAPI Backend](https://github.com/anttiviljami/openapi-backend/blob/master/DOCS.md)
209+
and [Ajv](https://ajv.js.org/) for more information.
185210

186-
When the `--silent` is provided, the proxy will forward the server's response body without modification. In this case, the validation headers are still added.
211+
When the `--silent` is provided, the proxy will forward the server's response body without modification. In this case,
212+
the validation headers are still added.
187213

188-
#### Module Usage
214+
### Module Usage
189215

190216
To run the proxy programatically use `runProxy`, which returns a `Promise<http.Server>`:
191217

@@ -202,7 +228,6 @@ const server = await runProxy({
202228
});
203229
```
204230

205-
206231
## FAQ
207232

208233
<details>

0 commit comments

Comments
 (0)