1 | <div align="center">
|
2 | <a href="https://swagger.io/docs/specification/about/">
|
3 | <img src="https://raw.githubusercontent.com/aleksandryackovlev/openapi-mock-express-middleware/master/assets/openapi-logo.png" alt="Open API logo" width="200" height="200">
|
4 | </a>
|
5 | <a href="https://github.com/expressjs/express">
|
6 | <img src="https://raw.githubusercontent.com/aleksandryackovlev/openapi-mock-express-middleware/master/assets/express-logo.png" alt="Express logo" width="465" height="141">
|
7 | </a>
|
8 | </div>
|
9 |
|
10 | [![npm][npm]][npm-url]
|
11 | [![deps][deps]][deps-url]
|
12 | [![Build Status](https://travis-ci.org/aleksandryackovlev/openapi-mock-express-middleware.svg?branch=master)](https://travis-ci.org/aleksandryackovlev/openapi-mock-express-middleware)
|
13 | [![codecov](https://codecov.io/gh/aleksandryackovlev/openapi-mock-express-middleware/branch/master/graph/badge.svg)](https://codecov.io/gh/aleksandryackovlev/openapi-mock-express-middleware)
|
14 | [![size](https://packagephobia.now.sh/badge?p=openapi-mock-express-middleware)](https://packagephobia.now.sh/result?p=openapi-mock-express-middleware)
|
15 |
|
16 | # openapi-mock-express-middleware
|
17 |
|
18 | Generates an express mock server from an [Open API 3.0](https://swagger.io/docs/specification/about/) documentation.
|
19 |
|
20 | ## Installation
|
21 |
|
22 | To begin, you'll need to install `openapi-mock-express-middleware`:
|
23 |
|
24 | ```console
|
25 | $ npm install openapi-mock-express-middleware --save-dev
|
26 | ```
|
27 |
|
28 | ## Usage
|
29 | ### Simple Config
|
30 | ```javascript
|
31 | const express = require('express');
|
32 | const { createMockMiddleware } = require('openapi-mock-express-middleware');
|
33 |
|
34 | const app = express();
|
35 |
|
36 | app.use(
|
37 | '/api', // root path for the mock server
|
38 | createMockMiddleware({ spec: '/absolute/path/to/your/openapi/spec.yml' }),
|
39 | );
|
40 |
|
41 | app.listen(80, () => console.log('Server listening on port 80'));
|
42 | ```
|
43 |
|
44 | ### Advanced Config
|
45 | The middleware uses [json-schmea-faker](https://github.com/json-schema-faker/json-schema-faker) under the hood. To configure it, you can pass locale and the options object to the factory function. (The full list of available options can be seen [here](https://github.com/json-schema-faker/json-schema-faker/tree/master/docs#available-options))
|
46 |
|
47 | ```javascript
|
48 | const express = require('express');
|
49 | const { createMockMiddleware } = require('openapi-mock-express-middleware');
|
50 |
|
51 | const app = express();
|
52 |
|
53 | app.use(
|
54 | '/api',
|
55 | createMockMiddleware({
|
56 | spec: '/absolute/path/to/your/openapi/spec.yml', // string or OpenAPIV3.Document object
|
57 | locale: 'ru', // json-schema-faker locale, default to 'en'
|
58 | options: { // json-schema-faker options
|
59 | alwaysFakeOptionals: true,
|
60 | useExamplesValue: true,
|
61 | // ...
|
62 | },
|
63 | jsfCallback: (jsf, faker) => {
|
64 | // function where you can extend json-schema-faker
|
65 | ...
|
66 | }
|
67 | }),
|
68 | );
|
69 |
|
70 | app.listen(80, () => console.log('Server listening on port 80'));
|
71 | ```
|
72 |
|
73 | ## Mock data
|
74 | ### Basic behavior
|
75 | By default midleware generates random responses depending on the types specified in the openapi docs.
|
76 |
|
77 | **doc.yml**
|
78 | ```
|
79 | ...
|
80 | paths:
|
81 | /company
|
82 | get:
|
83 | responses:
|
84 | '200':
|
85 | content:
|
86 | application/json:
|
87 | schema:
|
88 | type: object
|
89 | required:
|
90 | - id
|
91 | - number
|
92 | properties:
|
93 | id:
|
94 | type: string
|
95 | number:
|
96 | type: integer
|
97 | ...
|
98 | ```
|
99 |
|
100 | **GET /company response**
|
101 | ```javascript
|
102 | {
|
103 | id: 'dolor veniam consequat laborum',
|
104 | number: 68385409.
|
105 | }
|
106 | ```
|
107 |
|
108 | ### Faker generated responses
|
109 | In addition faker functions can be specified for data generation. The list of all available function can be found in the [faker documentation](https://github.com/marak/Faker.js/#api-methods).
|
110 |
|
111 | **doc.yml**
|
112 | ```
|
113 | ...
|
114 | paths:
|
115 | /user
|
116 | get:
|
117 | responses:
|
118 | '200':
|
119 | content:
|
120 | application/json:
|
121 | schema:
|
122 | type: object
|
123 | required:
|
124 | - id
|
125 | - name
|
126 | properties:
|
127 | id:
|
128 | type: string
|
129 | x-faker: random.uuid
|
130 | name:
|
131 | type: string
|
132 | x-faker: name.findName
|
133 | ...
|
134 | ```
|
135 |
|
136 | **GET /user response**
|
137 | ```javascript
|
138 | {
|
139 | id: '8c4a4ed2-efba-4913-9604-19a27f36f322',
|
140 | name: 'Mr. Braxton Dickens'.
|
141 | }
|
142 | ```
|
143 |
|
144 | ### Responses generated from examples
|
145 | If an example for the response object is specified, it will be used as a resulting sever response.
|
146 |
|
147 | **doc.yml**
|
148 | ```
|
149 | ...
|
150 | paths:
|
151 | /user
|
152 | get:
|
153 | responses:
|
154 | '200':
|
155 | content:
|
156 | application/json:
|
157 | schema:
|
158 | type: object
|
159 | example:
|
160 | id: 'id-125'
|
161 | name: 'John Smith'
|
162 | required:
|
163 | - id
|
164 | - name
|
165 | properties:
|
166 | id:
|
167 | type: string
|
168 | x-faker: random.uuid
|
169 | name:
|
170 | type: string
|
171 | x-faker: name.findName
|
172 | ...
|
173 | ```
|
174 |
|
175 | **GET /user response**
|
176 | ```javascript
|
177 | {
|
178 | id: 'id-125',
|
179 | name: 'John Smith'.
|
180 | }
|
181 | ```
|
182 |
|
183 | If multiple examples for the response object are specified, the first one will be used as a resulting sever response.
|
184 |
|
185 | **doc.yml**
|
186 | ```
|
187 | ...
|
188 | paths:
|
189 | /user
|
190 | get:
|
191 | responses:
|
192 | '200':
|
193 | content:
|
194 | application/json:
|
195 | schema:
|
196 | type: object
|
197 | examples:
|
198 | first:
|
199 | value:
|
200 | id: 'id-125'
|
201 | name: 'John Smith'
|
202 | second:
|
203 | value:
|
204 | id: 'some-other-id'
|
205 | name: 'Joe Doe'
|
206 | required:
|
207 | - id
|
208 | - name
|
209 | properties:
|
210 | id:
|
211 | type: string
|
212 | x-faker: random.uuid
|
213 | name:
|
214 | type: string
|
215 | x-faker: name.findName
|
216 | ...
|
217 | ```
|
218 |
|
219 | **GET /user response**
|
220 | ```javascript
|
221 | {
|
222 | id: 'id-125',
|
223 | name: 'John Smith'.
|
224 | }
|
225 | ```
|
226 |
|
227 | ## Contributing
|
228 |
|
229 | Please take a moment to read our contributing guidelines if you haven't yet done so.
|
230 |
|
231 | [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
232 |
|
233 | ## License
|
234 |
|
235 | [MIT](./LICENSE)
|
236 |
|
237 |
|
238 | [npm]: https://img.shields.io/npm/v/openapi-mock-express-middleware.svg
|
239 | [npm-url]: https://npmjs.com/package/openapi-mock-express-middleware
|
240 | [deps]: https://david-dm.org/aleksandryackovlev/openapi-mock-express-middleware.svg
|
241 | [deps-url]: https://david-dm.org/aleksandryackovlev/openapi-mock-express-middleware
|