CLI

The command line tool provided by Keq can compile the swagger document into typescript code. So that HTTP requests can be sent like calling functions.

Install

npm

npm install keq-cli

pnpm

pnpm install keq-cli

yarn

yarn install keq-cli

IMPORTANT

It is recommended to lock the version of keq-cli in package.json. Minor version of keq-cli may modify code template to fix bugs. This may cause code incompatibility.

Usage

Add a swagger file and .keqrc.ts file to project:

.keqrc.ts

import { defineKeqConfig, FileNamingStyle } from "keq-cli"

export default defineKeqConfig({
  outdir: "./src/api",
  fileNamingStyle: FileNamingStyle.snakeCase,
  modules: {
    catService: "./cat-service-swagger.json",
    // can also get the swagger document from internet, for example:
    // dogService: "http://dog.example.com/swagger.json"
  },
})

cat-service-swagger.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Cat Service",
    "version": "0.0.1"
  },
  "paths": {
    "/cat": {
      "get": {
        "operationId": "getCat",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cat"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Cat": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "age": { "type": "number" }
        }
      }
    }
  }
}

Run npx keq-cli build in the project directory to generate typescript code. The results are as follows:

./src/api/cat_service/get_cat.ts

import { Keq } from "keq"
import { request } from "keq"
import type {
  RequestParameters,
  ResponseMap,
  Operation,
} from "./types/get_cat"

export function getCat<STATUS extends keyof ResponseMap>(
  arg?: RequestParameters
): Keq<ResponseMap[STATUS], Operation<STATUS>> {
  const req = request.get<ResponseMap[STATUS]>("/cat").option("module", {
    name: "catService",
    pathname: "/cat",
  })

  return req as unknown as Keq<ResponseMap[STATUS], Operation<STATUS>>
}

./src/api/cat_service/components/schemas/cat.ts

/**
 * @interface Cat
 * @export
 */
export interface Cat {
  "name"?: string
  "age"?: number
}

./src/api/cat_service/types/get_cat.ts

import type { KeqOperation } from 'keq'
import type { Cat } from "../components/schemas/cat"


export interface ResponseMap {
  "200": Cat
}


export type QueryParameters = {
}

export type RouteParameters = {
}

export type HeaderParameters = {
}

export type BodyParameters ={}
export type RequestParameters = QueryParameters & RouteParameters & HeaderParameters & BodyParameters


export interface Operation<STATUS extends keyof ResponseMap> extends KeqOperation {
  requestParams: RouteParameters
  requestQuery: QueryParameters
  requestHeaders: HeaderParameters
  requestBody: BodyParameters
  responseBody: ResponseMap[STATUS]
}

Use the generated function to send an HTTP request:

import { getCat } from "./src/api/cat_service/get_cat"

const cat = await getCat()
  .retry(3, 1000)
  .timeout(1000)

console.log(`Cat name is ${cat.name}`)

And we can add error handler to the requests of catService module:

import { request } from 'keq'
import { throwException, RequestException } from 'keq-exception'


request
  .useRouter()
  .module('catService', throwException(context => {
    if (context.response) {
      if (context.response.status >= 400 && context.response.status < 500) {
        throw new RequestException(context.response.status, context.response.statusText, false)
      } else if (context.response.status >= 500) {
        throw new RequestException(context.response.status, context.response.statusText)
      }
    }
  }))

TIP

Thanks to the chain call and middleware, we can adjust the behavior of request without modifying code generated by keq-cli.

Configuration

keq-cli will look for files named .keqrc.yml、.keqrc.json、.keqrc.js、.keqrc.ts. And you can set the config file path using -c --config <config_file_path>.

Properties	Required	Default	Description
outdir	true	-	Output directory of results
fileNamingStyle	false	-	The file naming style.
modules	true	-	Swagger file location and module name
operationIdFactory	false	({ operation }) => operation.operationId	Defines how to generate function name. Default, the operationId in the swagger file is used.
strict	false	false	Clear outdir before generate.
esm	false	false	Whether to generate ESM style code.

FileNamingStyle

Enum	Example
FileNamingStyle.camelCase	"twoWords"
FileNamingStyle.capitalCase	"Two Words"
FileNamingStyle.constantCase	"TWO_WORDS"
FileNamingStyle.dotCase	"two.words"
FileNamingStyle.headerCase	"Tow-Words"
FileNamingStyle.noCase	"two words"
FileNamingStyle.paramCase	"two-words"
FileNamingStyle.pascalCase	"TwoWords"
FileNamingStyle.pathCase	"two/words"
FileNamingStyle.sentenceCase	"Two words"
FileNamingStyle.snakeCase	"two_words"

Command Line Options

Options	Description
[moduleName]	Only generate the specified module.
-c --config <config_file_path>	Configuration file address.
-i --interactive	Interactively specify the HTTP interface to be generated.
--method <method...>	Only generate function matching method ('get' | 'post' | 'put' | 'patch' | 'head' | 'options' | 'delete').
--pathname <pathname...>	Only generate function matching pathname.
--no-append	Do not generate newly added functions (compared with the last generation).
--no-update	Do not update the last generated functions.