free-swagger-client

输入 swagger 文档，返回接口代码片段

free-swagger，free-swagger-cli，free-swagger-extend 都是基于 free-swagger-client 封装的上层插件

快速上手

import freeSwaggerClient from "free-swagger-client";

const code = freeSwaggerClient(config, url, method);
console.log(code);

`
// 增加属性
export const addUsingPOST = params =>
  axios.request({
    url: "/attribute/add",
    method: "post",
    responseType: "json",
    params: {},
    data: params
  });
`;

API

| 参数 | 说明 | 类型 | 可选值 | 默认值 | | ------ | ------ | ------ | ------ | ------ | | config | 配置项 | Config | - | - | | url | - | string | - | - | | method | - | string | - | - |

• Config

| 参数 | 说明 | 类型 | 可选值 | 默认值 | | ---------------- | --------------------------- | ------------------------ | ----------- | ------------------------------------ | | source | 必选，swagger 源 | json | - | - | | lang | 可选，生成 api 语言 | string | "js" / "ts" | "js" | | templateFunction | 可选，模版函数 | Function(TemplateConfig) | - | 返回一个模版，用于生成自定义代码片段 | | jsDoc | 可选，代码块附加 jsdoc 注释 | boolean | - | true | | typedef | 可选，代码块附加 js doc typedef | boolean | | false | | interface | 可选，代码块附加 interface | boolean | - | false | | recursive | 可选，递归解析 jsDoc/interface 的依赖 | boolean | - | false |

• TemplateConfig

| 参数 | 说明 | 类型 | 可选值 | 默认值 | | ------------ | ------------------------------------ | -------- | -------- | ------ | | url | 路径 | string | - | - | | summary | 注释，对应 swagger 源 summary 字段 | string | - | - | | method | 接口请求方法 | string | - | - | | name | 名称，对应 swagger 源 operationId 字段 | string | - | - | | responseType | 返回值类型 | string | 同 axios responseType | - | | pathParams | 路径参数 | string[] | - | | IResponse | 返回值接口类型 | string | - | - | | IQueryParams | 请求值接口类型（请求参数） | string | - | - | | IBodyParams | 请求值接口类型（请求体） | string | - | - | | IPathParams | 路径参数接口类型 | string | - | - |

默认模版

free-swagger-client 基于模版函数来生成最终的 api 代码，用户可以自定义模版函数，来满足不同需求，例如修改请求库名，修改参数位置，修改接口命名等等

以下为 free-swagger-client 提供的默认模版

https://github.com/yeyan1996/free-swagger/blob/master/packages/client/src/default/template.ts

js 代码模版

({
     url,            // 完整路径 {string}
     summary,        // 注释 {string}
     method,         // 请求方法 {string}
     name,           // api 函数名 {string}
     responseType,   // 响应值种类，同 axios {string}
     pathParams,     // 路径参数 {Array<string>}
     IQueryParams,   // 请求查询参数 ts 类型
     IBodyParams,    // 请求体参数 ts 类型
     IPathParams     // 请求路径参数 ts 类型
 }) => {
    /**
      * js 代码模版
    **/ 
      
    // debugger
    // 可通过 debugger 调试模版

    // 处理路径参数 `/pet/{id}` => `/pet/${id}`
    const parsedUrl = url.replace(/{(.*?)}/g, '${$1}');

    // 有 query 和 body 参数
    const multipleParamsCondition = ({ IQueryParams, IBodyParams }) =>
        IQueryParams && IBodyParams

  const firstParamCodeMap = new Map()
      // 只有 query 参数，可能有 path 参数
      .set(
        ({ IQueryParams, IBodyParams }) => IQueryParams && !IBodyParams,
         `params,`
      )
      // 只有 body 参数，可能有 path 参数
      .set(
        ({ IQueryParams, IBodyParams }) => IBodyParams && !IQueryParams,
         `params,`
      )
      // 有 query 和 body 参数，可能有 path 参数
      .set(
        multipleParamsCondition,
        () => `queryParams,`
      )
       // 没有 query body 参数，有 path 参数
      .set(
        ({ IQueryParams,pathParams,IBodyParams }) => !IBodyParams && !IQueryParams && pathParams.length,
        '_NOOP,'
      )  
      // 只有 path 参数
      .set(
        ({ pathParams }) => pathParams.length,
        ({ pathParams }) =>
          `{${pathParams.join(',')}},`
      )

    const secondParamCodeMap = new Map()
        // 有 path 参数
        .set(
          ({ pathParams }) => pathParams.length,
          ({ pathParams }) =>
            `{${pathParams.join(',')}},`
        )
        // 有 query 和 body 参数，有 path 参数
        .set(multipleParamsCondition, `_NOOP,`)
        
      const thirdParamCodeMap = new Map()
        // 有 query 和 body 参数，有 path 参数
        .set(
          multipleParamsCondition,
          `bodyParams,`
        )
        
      const paramCodeMap = new Map()
        .set(multipleParamsCondition, 'queryParams,')
        .set(({ IQueryParams }) => !!IQueryParams, 'params,')
        
      const dataCodeMap = new Map()
        .set(multipleParamsCondition, 'bodyParams,')
        .set(({ IBodyParams }) => !!IBodyParams, 'params,')
    
      const createParamCode = (conditionMap, defaultCode = '') => {
        let code = defaultCode
        for (const [condition, codeFunction] of conditionMap.entries()) {
          const res = condition({
            IQueryParams,
            IBodyParams,
            pathParams,
          })
          if (res) {
            code =
              typeof codeFunction === 'string'
                ? codeFunction
                : codeFunction({
                    IQueryParams,
                    IBodyParams,
                    IPathParams,
                    pathParams,
                  })
            break
          }
        }
        return code
      }
     
    return `
  ${summary ? `// ${summary}` : ""}
  export const ${name} = (
    ${createParamCode(firstParamCodeMap) /* query | body | NOOP */}
    ${createParamCode(secondParamCodeMap) /* path | null */}
    ${createParamCode(thirdParamCodeMap) /* body | null */}
) => axios.request({
     url: \`${parsedUrl}\`,
     method: "${method}",
     params:${createParamCode(paramCodeMap, '{},')}
     data:${createParamCode(dataCodeMap, '{},')}
     ${responseType === "json" ? "" : `responseType: ${responseType},`}
 })`;
}

ts 代码模版

({
     url,            // 完整路径 {string}
     summary,        // 注释 {string}
     method,         // 请求方法 {string}
     name,           // api 函数名 {string}
     responseType,   // 响应值种类，同 axios {string}
     pathParams,     // 路径参数 {Array<string>}
     IQueryParams,   // 请求查询参数 ts 类型
     IBodyParams,    // 请求体参数 ts 类型
     IPathParams,     // 请求路径参数 ts 类型
     IResponse,      // 响应参数 ts 类型
 }) => {
    /**
      * ts 代码模版
    **/ 
      
    // debugger
    // 可通过 debugger 调试模版

    // 处理路径参数 `/pet/{id}` => `/pet/${id}`
      const parsedUrl = url.replace(/{(.*?)}/g, '${$1}'); 
     
      // 有 query 和 body 参数
      const multipleParamsCondition = ({ IQueryParams, IBodyParams }) =>
        IQueryParams && IBodyParams
        
      const firstParamCodeMap = new Map()
        // 只有 query 参数，可能有 path 参数
        .set(
          ({ IQueryParams, IBodyParams }) => IQueryParams && !IBodyParams,
          ({ IQueryParams }) => `params: ${IQueryParams},`
        )
        // 只有 body 参数，可能有 path 参数
        .set(
          ({ IQueryParams, IBodyParams }) => IBodyParams && !IQueryParams,
          ({ IBodyParams }) => `params: ${IBodyParams},`
        )
        // 有 query 和 body 参数，可能有 path 参数
        .set(
          multipleParamsCondition,
          ({ IQueryParams }) => `queryParams: ${IQueryParams},`
        )
        // 没有 query body 参数，有 path 参数
        .set(
          ({ IQueryParams,pathParams,IBodyParams }) => !IBodyParams && !IQueryParams && pathParams.length,
          '_NOOP: Record<string,never>,'
        )
         // 只有 path 参数
        .set(
          ({ pathParams }) => pathParams.length,
          ({ pathParams, IPathParams }) =>
            `{${pathParams.join(',')}}: ${IPathParams},`
        )
        
      const secondParamCodeMap = new Map()
        // 有 path 参数
        .set(
          ({ pathParams }) => pathParams.length,
          ({ pathParams, IPathParams }) =>
            `{${pathParams.join(',')}}: ${IPathParams},`
        )
        // 有 query 和 body 参数，有 path 参数
        .set(multipleParamsCondition, `_NOOP:{[key:string]: never},`)
        
      const thirdParamCodeMap = new Map()
        // 有 query 和 body 参数，有 path 参数
        .set(
          multipleParamsCondition,
          ({ IBodyParams }) => `bodyParams: ${IBodyParams},`
        )
        
      const paramCodeMap = new Map()
        .set(multipleParamsCondition, 'queryParams,')
        .set(({ IQueryParams }) => !!IQueryParams, 'params,')
        
      const dataCodeMap = new Map()
        .set(multipleParamsCondition, 'bodyParams,')
        .set(({ IBodyParams }) => !!IBodyParams, 'params,')
    
      const createParamCode = (conditionMap, defaultCode = '') => {
        let code = defaultCode
        for (const [condition, codeFunction] of conditionMap.entries()) {
          const res = condition({
            IQueryParams,
            IBodyParams,
            pathParams,
          })
          if (res) {
            code =
              typeof codeFunction === 'string'
                ? codeFunction
                : codeFunction({
                    IQueryParams,
                    IBodyParams,
                    IPathParams,
                    pathParams,
                  })
            break
          }
        }
        return code
      }

    return `
  ${summary ? `// ${summary}` : ""}  
  export const ${name} = (
    ${createParamCode(firstParamCodeMap) /* query | body | NOOP */}
    ${createParamCode(secondParamCodeMap) /* path | null */}
    ${createParamCode(thirdParamCodeMap) /* body | null */}
) => axios.request<${IResponse || "any"}>({
     url: \`${parsedUrl}\`,
     method: "${method}",
     params:${createParamCode(paramCodeMap, '{},')}
     data:${createParamCode(dataCodeMap, '{},')}
     ${responseType === "json" ? "" : `responseType: ${responseType},`}
 })`;
}