UNPKG

9.26 kBMarkdownView Raw
1# Spot
2
3**Spot** (_"Single Point Of Truth"_) is a concise, developer-friendly way to describe your API contract.
4
5Leveraging the TypeScript syntax, it lets you describe your API and generate other API contract formats you need (OpenAPI, Swagger, JSON Schema).
6
7You don't need to use TypeScript in your codebase to benefit from using Spot.
8
9Example of an API definition file `api.ts` which defines a single `POST` endpoint to create a user:
10
11```typescript
12import { api, endpoint, request, response, body } from "@airtasker/spot";
13
14@api({
15 name: "My API"
16})
17class Api {}
18
19@endpoint({
20 method: "POST",
21 path: "/users"
22})
23class CreateUser {
24 @request
25 request(@body body: CreateUserRequest) {}
26
27 @response({ status: 201 })
28 response(@body body: CreateUserResponse) {}
29}
30
31interface CreateUserRequest {
32 firstName: string;
33 lastName: string;
34}
35
36interface CreateUserResponse {
37 firstName: string;
38 lastName: string;
39 role: string;
40}
41```
42
43## Getting Started
44
45Get started with writing Spot contracts - [Spot Guide](https://github.com/airtasker/spot/wiki/Spot-Guide)
46
47For all available syntax, see [Spot Syntax](https://github.com/airtasker/spot/wiki/Spot-Syntax)
48
49### Installation
50
51With [yarn](https://yarnpkg.com/en/docs/usage) installed and initialized add `@airtasker/spot` to your project:
52
53```sh
54yarn add @airtasker/spot
55```
56
57You can pass the definition above to a generator by simply running:
58
59```sh
60npx @airtasker/spot generate --contract api.ts
61```
62
63# Why we built Spot
64
65At first glance, you may wonder why we bothered building Spot. Why not use OpenAPI (formely known as Swagger) to describe your API?
66
67At the core, we built Spot because we wanted a better developer experience.
68
69## Writing contracts
70
71OpenAPI 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
73Since 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
77We 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
79Because 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
81Spot 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
85Depending 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
87We 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<!-- toc -->
96* [Spot](#spot)
97* [Why we built Spot](#why-we-built-spot)
98* [Usage](#usage)
99* [Commands](#commands)
100<!-- tocstop -->
101
102# Usage
103
104To get started and set up an API declaration in the current directory, run:
105
106```
107npx @airtasker/spot init
108```
109
110You can then run a generator with:
111
112```
113npx @airtasker/spot generate --contract api.ts
114```
115
116# Commands
117
118<!-- commands -->
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
131Generate a checksum for a Spot contract
132
133```
134USAGE
135 $ spot checksum SPOT_CONTRACT
136
137ARGUMENTS
138 SPOT_CONTRACT path to Spot contract
139
140OPTIONS
141 -h, --help show CLI help
142
143EXAMPLE
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
151Preview Spot contract as OpenAPI3 documentation. The documentation server will start on http://localhost:8080.
152
153```
154USAGE
155 $ spot docs SPOT_CONTRACT
156
157ARGUMENTS
158 SPOT_CONTRACT path to Spot contract
159
160OPTIONS
161 -h, --help show CLI help
162 -p, --port=port [default: 8080] Documentation server port
163
164EXAMPLE
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
172Runs a generator on an API. Used to produce client libraries, server boilerplates and well-known API contract formats such as OpenAPI.
173
174```
175USAGE
176 $ spot generate
177
178OPTIONS
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
185EXAMPLE
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
193display help for spot
194
195```
196USAGE
197 $ spot help [COMMAND]
198
199ARGUMENTS
200 COMMAND command to show help for
201
202OPTIONS
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
210Generates the boilerplate for an API.
211
212```
213USAGE
214 $ spot init
215
216OPTIONS
217 -h, --help show CLI help
218
219EXAMPLE
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
231Lint a Spot contract
232
233```
234USAGE
235 $ spot lint SPOT_CONTRACT
236
237ARGUMENTS
238 SPOT_CONTRACT path to Spot contract
239
240OPTIONS
241 -h, --help show CLI help
242
243EXAMPLE
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
251Run a mock server based on a Spot contract
252
253```
254USAGE
255 $ spot mock SPOT_CONTRACT
256
257ARGUMENTS
258 SPOT_CONTRACT path to Spot contract
259
260OPTIONS
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
268EXAMPLE
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
276Validate a Spot contract
277
278```
279USAGE
280 $ spot validate SPOT_CONTRACT
281
282ARGUMENTS
283 SPOT_CONTRACT path to Spot contract
284
285OPTIONS
286 -h, --help show CLI help
287
288EXAMPLE
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
296Start the spot contract validation server
297
298```
299USAGE
300 $ spot validation-server SPOT_CONTRACT
301
302ARGUMENTS
303 SPOT_CONTRACT path to Spot contract
304
305OPTIONS
306 -h, --help show CLI help
307 -p, --port=port [default: 5907] The port where application will be available
308
309EXAMPLE
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<!-- commandsstop -->