Parrot

Highly customizable and type safe tool to fetch the swagger json from yapi and convert it into ts modules with nunjunks template.

     

Installation

npm -D @stkevintan/parrot

Usage

// yapi.ts
import {Parrot} from '@stkevintan/parrot'

const {url, headers} from 'path/to/connect-config'

const tagMapper = (tag: string) => {
  switch(tag){
    case '用户': return 'user',
    case '权限': return 'auth',
    case '部门权限': return 'auth',
    default: return 'common'
  }
}

Parrot.fromHTTP(url, headers).then(parrot => parrot.convert({
  out: 'src/api.ts',
  tagMapper,
  templates: {
    // custom the header template
    header: require.resolve('./header.njk')
  },
  // only parse the response.data schema to interface 
  responseInterceptor: schema => {
    if (schema && schema.properties && schema.properties.data) {
      return schema.properties.data
    }
    return schema
  }
})).then((content) => {
  console.log('the content is generated with', content.split('\n').length, 'lines')
})

Then, you can exec this file by ts-node in bash:

ts-node -O '{"module":"commonjs"}' yapi

Finaly, the outfile src/api.ts will be generated, and you can use it as an api module like following:

//src/test.ts
import * as api from './api'

// get with params
api.user.getUsers({region: "cn"}).then(users => {
  console.log(users)
})

// post with json body
api.user.postUser({id: 1, name: 'kevin'}).then(ok => console.log(ok))

// post with formData, version 1
function uploadV1(file: File) {
  api.user.postAvatar({ avatar: file, desc: "xxx" }).then(ok => console.log(ok))
}

// post with formData, version 2
function uploadV2(file: File) {
  const form = new FormData()
  form.append("avatar", file)
  form.append("desc", "xxx")
  api.user.postAvatar(form)
}

Notice: all the api module and functions are type guaranteed. You can import the related interfaces or types as well

API Doc

Parrot

There are two ways to get a parrot instance:

import { Parrot } from '@stkevintan/parrot'

//Option one: (get the swagger content in some way)
const swagger = fs.readFileSync('swagger.json', { encoding: 'utf8' })
const parrot = new Parrot(swagger)

// Option two: (retrive the swagger content from remote url)
Parrot.fromHTTP(url, headers).then(parrot => { })

Method

writeSwagger(path: string, options?: Option): Promise<void>

type Option =  {
  stringify?: (value: any) => string
  encoding?: string | null
  mode?: string | number 
  flag?: string 
}

write the swagger json into file which path indicated the location of the file and stringify function can be customized. eg: write swagger content into yaml format:

import YAML from 'yamljs'
import { Parrot } from '@stkevintan/parrot'

Parrot.fromHTTP(url, headers)
  .then(parrot => {
    return parrot.writeSwagger('./swagger.yaml', { stringify: YAML.stringify.bind(YAML) })
  })
  .then(() => {
    console.log('done')
  })

convert(option: Option): Promise<string>

convert swagger to ts file. the Option interface's definition:

export type Part = 'header' | 'interface' | 'fn' | 'body'

export type InterfaceType = 'query' | 'path' | 'body' | 'formData' | 'response'

export type Method = 'get' | 'put' | 'patch' | 'post' | 'delete'

export interface Option {
  tagMapper?: (tag: string) => string | undefined
  tplRoot?: string
  templates?: {
    [key in Part]?: string
  }
  apiNameMapper?: (path: string, method: Method) => string
  interfaceNameMapper?: (apiName: string, type: InterfaceType) => string
  responseInterceptor?: (schema: Schema) => Schema
  out?: string
  skipBodyOfGet?: boolean
}

option	description	default
tagMapper	a function that map the swagger tag to a legal variable name	tag => 'tag' + index++
tplRoot	templates directory location, which must container the four template part: header, interface, fn, body
templates	custom the templates	{}
apiNameMapper	map the api to a legal function name	path + method
interfaceNameMapper	generate the interface name	apiName + type
responseInterceptor	a intercept function to preprocess the response schema before generate the interface, it is usefull to extract the exact response type that your api return like { code: 0, data: exact_data }	schema => schema
out	the file path to write out
skipBodyOfGet	whether or not to skip the body parameters of get request	true

Template

the template is using nunjunks format, and it has been divided into four parts:

part	description
header	the ts file header template, provided the HeaderContext enviroment
interface	the ts interface template, provided the InterfaceContext environment
fn	ths ts api function template, provided the FnContext environment
body	ths ts main module template, provided the BodyContext environment

The context definitions:

// more type definitions can be found in source: src/type.ts
export interface HeaderContext {
  date: string
  basePath: string
}

export interface InterfaceContext {
  name: string
  description?: string
  field?: Field
}

export interface FnContext {
  description?: string
  name: string
  url: string
  method: string
  query?: string
  body?: string
  path?: string
  response?: string
}

export interface BodyContext {
  tags: [string, TagDescr][]
}

The default templates is written in typescript with axios.

You can totally rewrite all the template by providing a custom tplRoot in options, or you can just replace some specific part by the templates options.

Source file can be found in: src/templates