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 mockServer = require('openapi-mock-express-middleware');
|
33 |
|
34 | const app = express();
|
35 | app.use(
|
36 | '/api' /* root path for the mock server */,
|
37 | mockServer({ file: '/absolute/path/to/your/openapi/spec.yml' })
|
38 | );
|
39 | app.listen(80, () => console.log('Server listening on port 80'))''
|
40 | ```
|
41 |
|
42 | ### Advanced Config
|
43 | 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))
|
44 | ```javascript
|
45 | const express = require('express');
|
46 | const mockServer = require('openapi-mock-express-middleware');
|
47 |
|
48 | const app = express();
|
49 | app.use(
|
50 | '/api', // root path for the mock server
|
51 | mockServer({
|
52 | file: '/absolute/path/to/your/openapi/spec.yml'
|
53 | locale: 'ru', // json-schema-faker locale, default to 'en'
|
54 | {
|
55 | alwaysFakeOptionals: true,
|
56 | useDefaultValue: true,
|
57 | // ...
|
58 | }, // json-schema-faker options
|
59 | })
|
60 | );
|
61 | app.listen(80, () => console.log('Server listening on port 80'))''
|
62 | ```
|
63 |
|
64 | ## Mock data
|
65 | ### Basic behavior
|
66 | By default midleware generates random responses depending on the types specified in the openapi docs.
|
67 |
|
68 | **doc.yml**
|
69 | ```
|
70 | ...
|
71 | paths:
|
72 | /company
|
73 | get:
|
74 | responses:
|
75 | '200':
|
76 | content:
|
77 | application/json:
|
78 | schema:
|
79 | type: object
|
80 | required:
|
81 | - id
|
82 | - number
|
83 | properties:
|
84 | id:
|
85 | type: string
|
86 | number:
|
87 | type: integer
|
88 | ...
|
89 | ```
|
90 |
|
91 | **GET /company response**
|
92 | ```javascript
|
93 | {
|
94 | id: 'dolor veniam consequat laborum',
|
95 | number: 68385409.
|
96 | }
|
97 | ```
|
98 |
|
99 | ### Faker generated responses
|
100 | 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).
|
101 |
|
102 | **doc.yml**
|
103 | ```
|
104 | ...
|
105 | paths:
|
106 | /user
|
107 | get:
|
108 | responses:
|
109 | '200':
|
110 | content:
|
111 | application/json:
|
112 | schema:
|
113 | type: object
|
114 | required:
|
115 | - id
|
116 | - name
|
117 | properties:
|
118 | id:
|
119 | type: string
|
120 | x-faker: random.uuid
|
121 | name:
|
122 | type: string
|
123 | x-faker: name.findName
|
124 | ...
|
125 | ```
|
126 |
|
127 | **GET /user response**
|
128 | ```javascript
|
129 | {
|
130 | id: '8c4a4ed2-efba-4913-9604-19a27f36f322',
|
131 | name: 'Mr. Braxton Dickens'.
|
132 | }
|
133 | ```
|
134 |
|
135 | ### Responses generated from examples
|
136 | If an example for the response object is specified, it will be used as a resulting sever response.
|
137 |
|
138 | **doc.yml**
|
139 | ```
|
140 | ...
|
141 | paths:
|
142 | /user
|
143 | get:
|
144 | responses:
|
145 | '200':
|
146 | content:
|
147 | application/json:
|
148 | schema:
|
149 | type: object
|
150 | example:
|
151 | id: 'id-125'
|
152 | name: 'John Smith'
|
153 | required:
|
154 | - id
|
155 | - name
|
156 | properties:
|
157 | id:
|
158 | type: string
|
159 | x-faker: random.uuid
|
160 | name:
|
161 | type: string
|
162 | x-faker: name.findName
|
163 | ...
|
164 | ```
|
165 |
|
166 | **GET /user response**
|
167 | ```javascript
|
168 | {
|
169 | id: 'id-125',
|
170 | name: 'John Smith'.
|
171 | }
|
172 | ```
|
173 |
|
174 | If multiple examples for the response object are specified, the first one will be used as a resulting sever response.
|
175 |
|
176 | **doc.yml**
|
177 | ```
|
178 | ...
|
179 | paths:
|
180 | /user
|
181 | get:
|
182 | responses:
|
183 | '200':
|
184 | content:
|
185 | application/json:
|
186 | schema:
|
187 | type: object
|
188 | examples:
|
189 | first:
|
190 | value:
|
191 | id: 'id-125'
|
192 | name: 'John Smith'
|
193 | second:
|
194 | value:
|
195 | id: 'some-other-id'
|
196 | name: 'Joe Doe'
|
197 | required:
|
198 | - id
|
199 | - name
|
200 | properties:
|
201 | id:
|
202 | type: string
|
203 | x-faker: random.uuid
|
204 | name:
|
205 | type: string
|
206 | x-faker: name.findName
|
207 | ...
|
208 | ```
|
209 |
|
210 | **GET /user response**
|
211 | ```javascript
|
212 | {
|
213 | id: 'id-125',
|
214 | name: 'John Smith'.
|
215 | }
|
216 | ```
|
217 |
|
218 | ## Contributing
|
219 |
|
220 | Please take a moment to read our contributing guidelines if you haven't yet done so.
|
221 |
|
222 | [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
223 |
|
224 | ## License
|
225 |
|
226 | [MIT](./LICENSE)
|
227 |
|
228 |
|
229 | [npm]: https://img.shields.io/npm/v/openapi-mock-express-middleware.svg
|
230 | [npm-url]: https://npmjs.com/package/openapi-mock-express-middleware
|
231 | [deps]: https://david-dm.org/aleksandryackovlev/openapi-mock-express-middleware.svg
|
232 | [deps-url]: https://david-dm.org/aleksandryackovlev/openapi-mock-express-middleware
|
233 |
|