1 | # Spot
|
2 |
|
3 | **Spot** (_"Single Point Of Truth"_) is a concise, developer-friendly way to describe your API contract.
|
4 |
|
5 | Leveraging the TypeScript syntax, it lets you describe your API and generate other API contract formats you need (OpenAPI, Swagger, JSON Schema).
|
6 |
|
7 | You don't need to use TypeScript in your codebase to benefit from using Spot.
|
8 |
|
9 | Example of an API definition file `api.ts` which defines a single `POST` endpoint to create a user:
|
10 |
|
11 | ```typescript
|
12 | import { api, endpoint, request, response, body } from "@airtasker/spot";
|
13 |
|
14 | @api({
|
15 | name: "My API"
|
16 | })
|
17 | class Api {}
|
18 |
|
19 | @endpoint({
|
20 | method: "POST",
|
21 | path: "/users"
|
22 | })
|
23 | class CreateUser {
|
24 | @request
|
25 | request(@body body: CreateUserRequest) {}
|
26 |
|
27 | @response({ status: 201 })
|
28 | response(@body body: CreateUserResponse) {}
|
29 | }
|
30 |
|
31 | interface CreateUserRequest {
|
32 | firstName: string;
|
33 | lastName: string;
|
34 | }
|
35 |
|
36 | interface CreateUserResponse {
|
37 | firstName: string;
|
38 | lastName: string;
|
39 | role: string;
|
40 | }
|
41 | ```
|
42 |
|
43 | ## Getting Started
|
44 |
|
45 | Get started with writing Spot contracts - [Spot Guide](https://github.com/airtasker/spot/wiki/Spot-Guide)
|
46 |
|
47 | For all available syntax, see [Spot Syntax](https://github.com/airtasker/spot/wiki/Spot-Syntax)
|
48 |
|
49 | ### Installation
|
50 |
|
51 | With [yarn](https://yarnpkg.com/en/docs/usage) installed and initialized add `@airtasker/spot` to your project:
|
52 |
|
53 | ```sh
|
54 | yarn add @airtasker/spot
|
55 | ```
|
56 |
|
57 | You can pass the definition above to a generator by simply running:
|
58 |
|
59 | ```sh
|
60 | npx @airtasker/spot generate --contract api.ts
|
61 | ```
|
62 |
|
63 | # Why we built Spot
|
64 |
|
65 | At first glance, you may wonder why we bothered building Spot. Why not use OpenAPI (formely known as Swagger) to describe your API?
|
66 |
|
67 | At the core, we built Spot because we wanted a better developer experience.
|
68 |
|
69 | ## Writing contracts
|
70 |
|
71 | OpenAPI documents are stored as YAML files, following a very specific schema. You won’t know that you used the wrong field name or forgot to wrap a type definition into a schema object unless you run a good OpenAPI linter. Most developers who aren’t intimately familiar with the OpenAPI specification end up using a visual editor such as Swagger Editor or Stoplight.
|
72 |
|
73 | Since Spot leverages the TypeScript syntax, all you need is to write valid TypeScript code. Your editor will immediately tell you when your code is invalid. It will tell you what’s missing, and you even get autocomplete for free. We could have picked any other typed language—TypeScript just happened to be one of the most concise and ubiquitous for us.
|
74 |
|
75 | ## Reviewing contracts
|
76 |
|
77 | We believe that API contracts should be checked into Git, or whichever code versioning system you use. In addition, API contracts should be systematically peer reviewed. It’s far too easy for a backend engineer to incorrectly assume what client engineers expect from an endpoint.
|
78 |
|
79 | Because of their complex nested structure and the richness of the OpenAPI specification, OpenAPI documents can be difficult to review in a pull request. They’re great for machines, but not always for humans.
|
80 |
|
81 | Spot aims to be as human-readable as possible. We’ve seen developers become a lot more engaged in discussions on pull requests for Spot contracts, compared to our previous OpenAPI documents.
|
82 |
|
83 | ## Interoperability with various formats
|
84 |
|
85 | Depending on what you're trying to achieve (testing, documentation, client code generation…), you'll find tools that only work with OpenAPI 2 (Swagger), and newer tools that only support OpenAPI 3. You may also find tools for a different API ecosystem such as JSON Schema or API Blueprint.
|
86 |
|
87 | We built Spot with this in mind. Instead of having to juggle various API format converters, Spot can generate every major API document format. This is why we called it "Single Point Of Truth".
|
88 |
|
89 | [![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
|
90 | [![Version](https://img.shields.io/npm/v/@airtasker/spot.svg)](https://npmjs.org/package/@airtasker/spot)
|
91 | [![CircleCI](https://circleci.com/gh/airtasker/spot/tree/master.svg?style=shield)](https://circleci.com/gh/airtasker/spot/tree/master)
|
92 | [![Downloads/week](https://img.shields.io/npm/dw/@airtasker/spot.svg)](https://npmjs.org/package/@airtasker/spot)
|
93 | [![License](https://img.shields.io/npm/l/@airtasker/spot.svg)](https://github.com/airtasker/spot/blob/master/package.json)
|
94 |
|
95 |
|
96 | * [Spot](#spot)
|
97 | * [Why we built Spot](#why-we-built-spot)
|
98 | * [Usage](#usage)
|
99 | * [Commands](#commands)
|
100 |
|
101 |
|
102 | # Usage
|
103 |
|
104 | To get started and set up an API declaration in the current directory, run:
|
105 |
|
106 | ```
|
107 | npx @airtasker/spot init
|
108 | ```
|
109 |
|
110 | You can then run a generator with:
|
111 |
|
112 | ```
|
113 | npx @airtasker/spot generate --contract api.ts
|
114 | ```
|
115 |
|
116 | # Commands
|
117 |
|
118 |
|
119 | * [`spot checksum SPOT_CONTRACT`](#spot-checksum-spot_contract)
|
120 | * [`spot docs SPOT_CONTRACT`](#spot-docs-spot_contract)
|
121 | * [`spot generate`](#spot-generate)
|
122 | * [`spot help [COMMAND]`](#spot-help-command)
|
123 | * [`spot init`](#spot-init)
|
124 | * [`spot lint SPOT_CONTRACT`](#spot-lint-spot_contract)
|
125 | * [`spot mock SPOT_CONTRACT`](#spot-mock-spot_contract)
|
126 | * [`spot validate SPOT_CONTRACT`](#spot-validate-spot_contract)
|
127 | * [`spot validation-server SPOT_CONTRACT`](#spot-validation-server-spot_contract)
|
128 |
|
129 | ## `spot checksum SPOT_CONTRACT`
|
130 |
|
131 | Generate a checksum for a Spot contract
|
132 |
|
133 | ```
|
134 | USAGE
|
135 | $ spot checksum SPOT_CONTRACT
|
136 |
|
137 | ARGUMENTS
|
138 | SPOT_CONTRACT path to Spot contract
|
139 |
|
140 | OPTIONS
|
141 | -h, --help show CLI help
|
142 |
|
143 | EXAMPLE
|
144 | $ spot checksum api.ts
|
145 | ```
|
146 |
|
147 | _See code: [build/cli/src/commands/checksum.js](https://github.com/airtasker/spot/blob/v1.1.2/build/cli/src/commands/checksum.js)_
|
148 |
|
149 | ## `spot docs SPOT_CONTRACT`
|
150 |
|
151 | Preview Spot contract as OpenAPI3 documentation. The documentation server will start on http://localhost:8080.
|
152 |
|
153 | ```
|
154 | USAGE
|
155 | $ spot docs SPOT_CONTRACT
|
156 |
|
157 | ARGUMENTS
|
158 | SPOT_CONTRACT path to Spot contract
|
159 |
|
160 | OPTIONS
|
161 | -h, --help show CLI help
|
162 | -p, --port=port [default: 8080] Documentation server port
|
163 |
|
164 | EXAMPLE
|
165 | $ spot docs api.ts
|
166 | ```
|
167 |
|
168 | _See code: [build/cli/src/commands/docs.js](https://github.com/airtasker/spot/blob/v1.1.2/build/cli/src/commands/docs.js)_
|
169 |
|
170 | ## `spot generate`
|
171 |
|
172 | Runs a generator on an API. Used to produce client libraries, server boilerplates and well-known API contract formats such as OpenAPI.
|
173 |
|
174 | ```
|
175 | USAGE
|
176 | $ spot generate
|
177 |
|
178 | OPTIONS
|
179 | -c, --contract=contract (required) Path to a TypeScript Contract definition
|
180 | -g, --generator=generator Generator to run
|
181 | -h, --help show CLI help
|
182 | -l, --language=language Language to generate
|
183 | -o, --out=out Directory in which to output generated files
|
184 |
|
185 | EXAMPLE
|
186 | $ spot generate --contract api.ts --language yaml --generator openapi3 --out output/
|
187 | ```
|
188 |
|
189 | _See code: [build/cli/src/commands/generate.js](https://github.com/airtasker/spot/blob/v1.1.2/build/cli/src/commands/generate.js)_
|
190 |
|
191 | ## `spot help [COMMAND]`
|
192 |
|
193 | display help for spot
|
194 |
|
195 | ```
|
196 | USAGE
|
197 | $ spot help [COMMAND]
|
198 |
|
199 | ARGUMENTS
|
200 | COMMAND command to show help for
|
201 |
|
202 | OPTIONS
|
203 | --all see all commands in CLI
|
204 | ```
|
205 |
|
206 | _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v2.2.3/src/commands/help.ts)_
|
207 |
|
208 | ## `spot init`
|
209 |
|
210 | Generates the boilerplate for an API.
|
211 |
|
212 | ```
|
213 | USAGE
|
214 | $ spot init
|
215 |
|
216 | OPTIONS
|
217 | -h, --help show CLI help
|
218 |
|
219 | EXAMPLE
|
220 | $ spot init
|
221 | Generated the following files:
|
222 | - api.ts
|
223 | - tsconfig.json
|
224 | - package.json
|
225 | ```
|
226 |
|
227 | _See code: [build/cli/src/commands/init.js](https://github.com/airtasker/spot/blob/v1.1.2/build/cli/src/commands/init.js)_
|
228 |
|
229 | ## `spot lint SPOT_CONTRACT`
|
230 |
|
231 | Lint a Spot contract
|
232 |
|
233 | ```
|
234 | USAGE
|
235 | $ spot lint SPOT_CONTRACT
|
236 |
|
237 | ARGUMENTS
|
238 | SPOT_CONTRACT path to Spot contract
|
239 |
|
240 | OPTIONS
|
241 | -h, --help show CLI help
|
242 |
|
243 | EXAMPLE
|
244 | $ spot lint api.ts
|
245 | ```
|
246 |
|
247 | _See code: [build/cli/src/commands/lint.js](https://github.com/airtasker/spot/blob/v1.1.2/build/cli/src/commands/lint.js)_
|
248 |
|
249 | ## `spot mock SPOT_CONTRACT`
|
250 |
|
251 | Run a mock server based on a Spot contract
|
252 |
|
253 | ```
|
254 | USAGE
|
255 | $ spot mock SPOT_CONTRACT
|
256 |
|
257 | ARGUMENTS
|
258 | SPOT_CONTRACT path to Spot contract
|
259 |
|
260 | OPTIONS
|
261 | -h, --help show CLI help
|
262 | -p, --port=port (required) [default: 3010] Port on which to run the mock server
|
263 | --pathPrefix=pathPrefix Prefix to prepend to each endpoint path
|
264 |
|
265 | --proxyBaseUrl=proxyBaseUrl If set, the server will act as a proxy and fetch data from the given remote server
|
266 | instead of mocking it
|
267 |
|
268 | EXAMPLE
|
269 | $ spot mock api.ts
|
270 | ```
|
271 |
|
272 | _See code: [build/cli/src/commands/mock.js](https://github.com/airtasker/spot/blob/v1.1.2/build/cli/src/commands/mock.js)_
|
273 |
|
274 | ## `spot validate SPOT_CONTRACT`
|
275 |
|
276 | Validate a Spot contract
|
277 |
|
278 | ```
|
279 | USAGE
|
280 | $ spot validate SPOT_CONTRACT
|
281 |
|
282 | ARGUMENTS
|
283 | SPOT_CONTRACT path to Spot contract
|
284 |
|
285 | OPTIONS
|
286 | -h, --help show CLI help
|
287 |
|
288 | EXAMPLE
|
289 | $ spot validate api.ts
|
290 | ```
|
291 |
|
292 | _See code: [build/cli/src/commands/validate.js](https://github.com/airtasker/spot/blob/v1.1.2/build/cli/src/commands/validate.js)_
|
293 |
|
294 | ## `spot validation-server SPOT_CONTRACT`
|
295 |
|
296 | Start the spot contract validation server
|
297 |
|
298 | ```
|
299 | USAGE
|
300 | $ spot validation-server SPOT_CONTRACT
|
301 |
|
302 | ARGUMENTS
|
303 | SPOT_CONTRACT path to Spot contract
|
304 |
|
305 | OPTIONS
|
306 | -h, --help show CLI help
|
307 | -p, --port=port [default: 5907] The port where application will be available
|
308 |
|
309 | EXAMPLE
|
310 | $ spot validation-server api.ts
|
311 | ```
|
312 |
|
313 | _See code: [build/cli/src/commands/validation-server.js](https://github.com/airtasker/spot/blob/v1.1.2/build/cli/src/commands/validation-server.js)_
|
314 |
|