@af_cargo/spot NPM

installation

npm i
npm i yarn

Publish a new version

upgrade the version in the package.json run the command : If the this is the first time you need to log to your npmjs account

npm login

npm run prepack
npm publish --access public

Servers

Spot allows to declare one or multiple server through open api 3 specification.

One server declaration could be :

import { api } from "@af_spot/spot";
import { oa3server } from "../../../syntax/oa3server";
import { oa3serverVariables } from "../../../syntax/oa3serverVariables";
import { String } from "@af_spot/spot";

@api({ name: "contract" })
class Contract {
  /**
   * Production server
   */
  @oa3server({ url: "https://dev.gigantic-server.com:8443/v1" })
  productionServer() {}
}

Or :

import { api } from "@af_spot/spot";
import { oa3server } from "../../../syntax/oa3server";
import { oa3serverVariables } from "../../../syntax/oa3serverVariables";
import { String } from "@af_spot/spot";

@api({ name: "contract" })
class Contract {
  /**
   * Production server
   */
  @oa3server({
    url: "https://{username}.gigantic-server.com:{port}/{basePath}"
  })
  productionServer(
    @oa3serverVariables
      variables: {
      /**
       * this value is assigned by the service provider, in this example `gigantic-server.com`
       *
       * @default "demo"
       */
      username: String;
      /**
       * @default "8443"
       */
      port: "8443" | "443";
      /**
       * @default "v2"
       */
      basePath: String;
    }
  ) {
  }
}

multiple server declaration could be :

import { api } from "@af_spot/spot";
import { oa3server } from "../../../syntax/oa3server";
import { oa3serverVariables } from "../../../syntax/oa3serverVariables";
import { String } from "@af_spot/spot";

@api({ name: "contract" })
class Contract {
  /**
   * Production server
   */
  @oa3server({
    url: "https://{username}.gigantic-server.com:{port}/{basePath}"
  })
  productionServer(
    @oa3serverVariables
    variables: {
      /**
       * this value is assigned by the service provider, in this example `gigantic-server.com`
       *
       * @default "demo"
       */
      username: String;
      /**
       * @default "8443"
       */
      port: "8443" | "443";
      /**
       * @default "v2"
       */
      basePath: String;
    }
  ) {}
  /**
   * dev server
   */
  @oa3server({
    url: "https://{username}.gigantic-server.com:{port}/{basePath}"
  })
  devServer(
    @oa3serverVariables
    variables: {
      /**
       * this value is assigned by the service provider, in this example `gigantic-server.com`
       *
       * @default "dev"
       */
      username: String;
      /**
       * @default "8080"
       */
      port: "8080" | "8081";
      /**
       * @default "v2"
       */
      basePath: String;
    }
  ) {}
}

Spot

Spot ("Single Point Of Truth") is a concise, developer-friendly way to describe your API contract.

Leveraging the TypeScript syntax, it lets you describe your API and generate other API contract formats you need (OpenAPI, Swagger, JSON Schema).

You don't need to use TypeScript in your codebase to benefit from using Spot.

Example of an API definition file api.ts which defines a single POST endpoint to create a user:

import { api, endpoint, request, response, body } from "@airtasker/spot";

@api({
    name: "My API"
})
class Api {}

@endpoint({
    method: "POST",
    path: "/users"
})
class CreateUser {
    @request
    request(@body body: CreateUserRequest) {}

    @response({ status: 201 })
    response(@body body: CreateUserResponse) {}
}

interface CreateUserRequest {
    firstName: string;
    lastName: string;
}

interface CreateUserResponse {
    firstName: string;
    lastName: string;
    role: string;
}

Getting Started

Get started with writing Spot contracts - Spot Guide

For all available syntax, see Spot Syntax

Installation

With yarn installed and initialized add @airtasker/spot to your project:

yarn add @airtasker/spot

You can pass the definition above to a generator by simply running:

npx @airtasker/spot generate --contract api.ts

Why we built Spot

At first glance, you may wonder why we bothered building Spot. Why not use OpenAPI (formely known as Swagger) to describe your API?

At the core, we built Spot because we wanted a better developer experience.

Writing contracts

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.

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.

Reviewing contracts

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.

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.

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.

Usage

To get started and set up an API declaration in the current directory, run:

npx @airtasker/spot init

You can then run a generator with:

npx @airtasker/spot generate --contract api.ts

In Memory Usage

import { Spot } from "@airtasker/spot";

const contract = Spot.parseContract("./api.ts")
const openApi = Spot.OpenApi3.generateOpenAPI3(contract);

console.log(openApi);

/*
{
  openapi: '3.0.2',
  info: { title: 'my-api', description: undefined, version: '0.0.0' },
  paths: { '/users': { post: [Object] } },
  components: {
    schemas: { CreateUserRequest: [Object], CreateUserResponse: [Object] },
    securitySchemes: undefined
  },
  security: undefined
}
*/

`spot checksum SPOT_CONTRACT`

Generate a checksum for a Spot contract

USAGE
  $ spot checksum SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot checksum api.ts

`spot docs SPOT_CONTRACT`

Preview Spot contract as OpenAPI3 documentation. The documentation server will start on http://localhost:8080.

USAGE
  $ spot docs SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help       show CLI help
  -p, --port=port  [default: 8080] Documentation server port

EXAMPLE
  $ spot docs api.ts

`spot generate`

Runs a generator on an API. Used to produce client libraries, server boilerplates and well-known API contract formats such as OpenAPI.

USAGE
  $ spot generate

OPTIONS
  -c, --contract=contract    (required) Path to a TypeScript Contract definition
  -g, --generator=generator  Generator to run
  -h, --help                 show CLI help
  -l, --language=language    Language to generate
  -o, --out=out              Directory in which to output generated files

EXAMPLE
  $ spot generate --contract api.ts --language yaml --generator openapi3 --out output/

`spot help [COMMAND]`

display help for spot

USAGE
  $ spot help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

See code: @oclif/plugin-help

`spot init`

Generates the boilerplate for an API.

USAGE
  $ spot init

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot init
  Generated the following files:
  - api.ts
  - tsconfig.json
  - package.json

`spot lint SPOT_CONTRACT`

Lint a Spot contract

USAGE
  $ spot lint SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot lint api.ts

`spot mock SPOT_CONTRACT`

Run a mock server based on a Spot contract

USAGE
  $ spot mock SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help                   show CLI help
  -p, --port=port              (required) [default: 3010] Port on which to run the mock server
  --pathPrefix=pathPrefix      Prefix to prepend to each endpoint path

  --proxyBaseUrl=proxyBaseUrl  If set, the server will act as a proxy and fetch data from the given remote server
                               instead of mocking it

EXAMPLE
  $ spot mock api.ts

`spot validate SPOT_CONTRACT`

Validate a Spot contract

USAGE
  $ spot validate SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot validate api.ts

`spot validation-server SPOT_CONTRACT`

Start the spot contract validation server

USAGE
  $ spot validation-server SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help       show CLI help
  -p, --port=port  [default: 5907] The port where application will be available

EXAMPLE
  $ spot validation-server api.ts

spot checksum SPOT_CONTRACT
spot docs SPOT_CONTRACT
spot generate
spot help [COMMAND]
spot init
spot lint SPOT_CONTRACT
spot mock SPOT_CONTRACT
spot validate SPOT_CONTRACT
spot validation-server SPOT_CONTRACT

`spot checksum SPOT_CONTRACT`

Generate a checksum for a Spot contract

USAGE
  $ spot checksum SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot checksum api.ts

`spot docs SPOT_CONTRACT`

Preview Spot contract as OpenAPI3 documentation. The documentation server will start on http://localhost:8080.

USAGE
  $ spot docs SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help       show CLI help
  -p, --port=port  [default: 8080] Documentation server port

EXAMPLE
  $ spot docs api.ts

`spot generate`

Runs a generator on an API. Used to produce client libraries, server boilerplates and well-known API contract formats such as OpenAPI.

USAGE
  $ spot generate

OPTIONS
  -c, --contract=contract    (required) Path to a TypeScript Contract definition
  -g, --generator=generator  Generator to run
  -h, --help                 show CLI help
  -l, --language=language    Language to generate
  -o, --out=out              Directory in which to output generated files

EXAMPLE
  $ spot generate --contract api.ts --language yaml --generator openapi3 --out output/

`spot help [COMMAND]`

display help for spot

USAGE
  $ spot help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

See code: @oclif/plugin-help

`spot init`

Generates the boilerplate for an API.

USAGE
  $ spot init

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot init
  Generated the following files:
  - api.ts
  - tsconfig.json
  - package.json

`spot lint SPOT_CONTRACT`

Lint a Spot contract

USAGE
  $ spot lint SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot lint api.ts

`spot mock SPOT_CONTRACT`

Run a mock server based on a Spot contract

USAGE
  $ spot mock SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help                   show CLI help
  -p, --port=port              (required) [default: 3010] Port on which to run the mock server
  --pathPrefix=pathPrefix      Prefix to prepend to each endpoint path

  --proxyBaseUrl=proxyBaseUrl  If set, the server will act as a proxy and fetch data from the given remote server
                               instead of mocking it

EXAMPLE
  $ spot mock api.ts

`spot validate SPOT_CONTRACT`

Validate a Spot contract

USAGE
  $ spot validate SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot validate api.ts

`spot validation-server SPOT_CONTRACT`

Start the spot contract validation server

USAGE
  $ spot validation-server SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help       show CLI help
  -p, --port=port  [default: 5907] The port where application will be available

EXAMPLE
  $ spot validation-server api.ts

spot checksum SPOT_CONTRACT
spot docs SPOT_CONTRACT
spot generate
spot help [COMMAND]
spot init
spot lint SPOT_CONTRACT
spot mock SPOT_CONTRACT
spot validate SPOT_CONTRACT
spot validation-server SPOT_CONTRACT

`spot checksum SPOT_CONTRACT`

Generate a checksum for a Spot contract

USAGE
  $ spot checksum SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot checksum api.ts

`spot docs SPOT_CONTRACT`

Preview Spot contract as OpenAPI3 documentation. The documentation server will start on http://localhost:8080.

USAGE
  $ spot docs SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help       show CLI help
  -p, --port=port  [default: 8080] Documentation server port

EXAMPLE
  $ spot docs api.ts

`spot generate`

Runs a generator on an API. Used to produce client libraries, server boilerplates and well-known API contract formats such as OpenAPI.

USAGE
  $ spot generate

OPTIONS
  -c, --contract=contract    (required) Path to a TypeScript Contract definition
  -g, --generator=generator  Generator to run
  -h, --help                 show CLI help
  -l, --language=language    Language to generate
  -o, --out=out              Directory in which to output generated files

EXAMPLE
  $ spot generate --contract api.ts --language yaml --generator openapi3 --out output/

`spot help [COMMAND]`

display help for spot

USAGE
  $ spot help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

See code: @oclif/plugin-help

`spot init`

Generates the boilerplate for an API.

USAGE
  $ spot init

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot init
  Generated the following files:
  - api.ts
  - tsconfig.json
  - package.json

`spot lint SPOT_CONTRACT`

Lint a Spot contract

USAGE
  $ spot lint SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot lint api.ts

`spot mock SPOT_CONTRACT`

Run a mock server based on a Spot contract

USAGE
  $ spot mock SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help                   show CLI help
  -p, --port=port              (required) [default: 3010] Port on which to run the mock server
  --pathPrefix=pathPrefix      Prefix to prepend to each endpoint path

  --proxyBaseUrl=proxyBaseUrl  If set, the server will act as a proxy and fetch data from the given remote server
                               instead of mocking it

EXAMPLE
  $ spot mock api.ts

`spot validate SPOT_CONTRACT`

Validate a Spot contract

USAGE
  $ spot validate SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot validate api.ts

`spot validation-server SPOT_CONTRACT`

Start the spot contract validation server

USAGE
  $ spot validation-server SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help       show CLI help
  -p, --port=port  [default: 5907] The port where application will be available

EXAMPLE
  $ spot validation-server api.ts

@oclif/command @oclif/config @oclif/plugin-help ajv assert-never cors express fs-extra inquirer js-yaml qs randomstring ts-morph typescript validator

@everything-registry/sub-chunk-31 @zalastax/nolb-_af @infinitebrahmanuniverse/nolb-_af

5 years ago

5 years ago

5 years ago

5 years ago