{"id":19463014,"url":"https://github.com/poppinlp/js-api-generator","last_synced_at":"2025-04-25T08:32:01.262Z","repository":{"id":36160496,"uuid":"40464569","full_name":"poppinlp/js-api-generator","owner":"poppinlp","description":"Generate javascript api module from config file.","archived":false,"fork":false,"pushed_at":"2018-12-04T08:22:51.000Z","size":608,"stargazers_count":5,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-03T19:06:21.164Z","etag":null,"topics":["ajax","api","codegen","defination","fetch","request"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/poppinlp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-10T05:22:17.000Z","updated_at":"2024-05-14T09:48:05.000Z","dependencies_parsed_at":"2022-08-17T23:40:47.363Z","dependency_job_id":null,"html_url":"https://github.com/poppinlp/js-api-generator","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poppinlp%2Fjs-api-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poppinlp%2Fjs-api-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poppinlp%2Fjs-api-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poppinlp%2Fjs-api-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/poppinlp","download_url":"https://codeload.github.com/poppinlp/js-api-generator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250782205,"owners_count":21486407,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ajax","api","codegen","defination","fetch","request"],"created_at":"2024-11-10T18:07:52.445Z","updated_at":"2025-04-25T08:32:00.965Z","avatar_url":"https://github.com/poppinlp.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# js-api-generator\n\n[![Build Status][ci-img]][ci-url]\n[![Dependency Status][dep-img]][dep-url]\n[![Dev Dependency Status][dev-dep-img]][dev-dep-url]\n[![NPM version][npm-ver-img]][npm-url]\n[![NPM downloads][npm-dl-img]][npm-url]\n[![NPM license][npm-lc-img]][npm-url]\n\nGenerate module for API requesting:\n\n- follow CommonJS specification or ES2015\n- from easy config file\n- with Promise returned\n- by XMLHttpRequest or fetch API (Current version use fetch API to request. Wish to use XMLHttpRequest? See [tag 0.2.4](https://github.com/poppinlp/js-api-generator/tree/v0.2.4))\n- builtin browserify and rollup\n- e.t.c\n\n## Getting Started\n\nInstall with this command:\n\n```shell\nnpm install js-api-generator --save\n```\n\nor maybe you like yarn:\n\n```shell\nyarn add js-api-generator\n```\n\n## About Generated Module\n\nThis part is for generated module.\n\n- Each API accepts an object param which will be sent as ajax data. The `needs` api config will be checked in this param.\n- Each API returns a Promise. Resolve or reject will determined by `isSuccess` api config.\n- Each API won't send request again before response or timeout, but callback will be queued which will all be triggered when get response or timeout.\n- The callback function accepts an object param which content is determined by `success` or `fail` api config.\n- The output module is in ES2015 syntax. You should do [babel](https://babeljs.io/) or [buble](https://buble.surge.sh/) yourself if you want.\n\n### Generated Module Usage Example\n\n#### Node env with CommonJS output\n\n```js\nvar api = require('path/to/generated-api-module');\n\napi.yourApiName({\n    // data to send\n}).then(res =\u003e {\n    // res object content is determined by `success` config\n    // do some stuff for success\n}, err =\u003e {\n    // err object content is determined by `fail` config\n    // do some stuff for fail\n});\n```\n\n#### Browser env with browserify or rollup output\n\n```html\n\u003cscript src=\"path/to/generated-api-module.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\napi.yourApiName({\n    // data to send\n}).then(res =\u003e {\n    // res object content is determined by `success` config\n    // do some stuff for success\n}, err =\u003e {\n    // err object content is determined by `fail` config\n    // do some stuff for fail\n});\n\u003c/script\u003e\n```\n\n## About Config File\n\nConfig file should be [YAML](http://www.yaml.org/spec/1.2/spec.html) format and should have `api` and `config` object.\n\n### api\n\nProvide api list. Each api could have follow options:\n\n#### url {String}\n\nThe url for requesting. Support dynamic url which means you could use variable in url link.\n\nIf the config url is `/user/:uid` and you call this API by `{uid: 123}`, the request url will be `/user/123`.\n\n#### rootUrl {String}\n\nThe global prefix should set at `config.rootUrl`.\nThis `api.rootUrl` option is used to cover that in some case.\n\n#### name {String}\n\nThe method name for this api in generated module.\n\n#### method {String}\n\nThe request method such as `post`. Ignore case.\n\n#### type {String}\n\nThe alias for `method`. [DEPRECATED]\n\n#### needs {Object | Array}\n\nDefault: `{}`\n\nIf this is an array, strings in it will be used as property name to check existent and not empty in request data. [DEPRECATED]\n\nIf this is an object, the key will be used as property name and the value as variable type(or type list) for data check. `Any` will be used if can't match any option. Supported variable type check list:\n\n- String\n- Number\n- Boolean\n- Array\n- Blob\n- Object\n- Null\n- Any\n\nIf any key is end with `?`, property name won't include the `?` and this key will be treated as optional.\n\n#### timeout {Number}\n\nLimit request timeout. Milliseconds.\n\n#### mode {String}\n\nThe request mode for fetch API. Could be `cors`, `no-cors`, `same-origin`, `navigate`, `websocket`.\n\n#### credentials {String}\n\nThe request credentials for fetch API. Could be `omit`, `same-origin`, `include`.\n\n#### cache {String}\n\nThe request cache for fetch API. Could be `default`, `no-store`, `reload`, `no-cache`, `force-cache`, `only-if-cached`.\n\nSince the cache option [only support in Firefox 48+](https://developer.mozilla.org/en-US/docs/Web/API/Request/cache#Browser_compatibility),\nthe request url will be added a query string automatically like what jQuery ajax cache did when the cache value is `reload`, `no-cache` or `no-store`.\n\n#### isSuccess {Object}\n\nUse to determine success or fail for requesting.\n\n- success: response object must has same key-value pair for every key-value pair in this object\n- fail: any mismatch\n\n#### success {Array}\n\nUse to constitute a callback param when success.\n\n#### fail {Array}\n\nUse to constitute a callback param when fail.\n\n#### headers {Object}\n\nUse to add custom request headers. Such as `X-Requested-With`.\n\n#### dataType {String}\n\nUse to construct data for request body. Ignore case. `Origin` will be used if can't match any option. Supported type list:\n\n##### URLSearchParams\n\nUse [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) to construct passed in data.\nMaybe you need [this polyfill](https://github.com/poppinlp/simple-url-search-params) for IE.\n\nThis package will set `Content-Type` to `application/x-www-form-urlencoded` for request header automatically since some browser don't support `URLSearchParams` and they won't add that header even if you use `URLSearchParams` polyfill. You could overwrite it by `headers` option.\n\n##### FormData\n\nUse [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) to construct passed in data.\n\nBrowser will set `Content-Type` to `multipart/form-data` for request header automatically.\n\n##### JSON\n\nThis option will stringify passed in data to a JSON string by [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).\n\nThis package will set `Content-Type` to `application/json` instead of `text/plain` for request header automatically since browser won't do that. You could overwrite it by `headers` option.\n\n##### Origin\n\nWon't do anything for passed in data and pass it through to fetch body.\n\n### config\n\nProvide global options. Could have follow options:\n\n#### promise {String}\n\nDefault: `Promise`\n\nThe global promise object in your environment.\n\n#### method {String}\n\nDefault: `get`\n\nThe request method such as `post`. Ignore case.\nFor all api. Will be covered by `api.type`.\n\n#### type {String}\n\nThe alias for `method`. [DEPRECATED]\n\n#### cache {String}\n\nDefault: `default`\n\nFor all api. Will be covered by `api.cache`.\n\n#### mode {String}\n\nDefault: `same-origin`\n\nFor all api. Will be covered by `api.mode`.\n\n#### credentials {String}\n\nDefault: `same-origin`\n\nFor all api. Will be covered by `api.credentials`.\n\n#### isSuccess {Object}\n\nDefault: `{}`\n\nFor all api. Will be covered by `api.isSuccess`.\n\n#### timeout {Number}\n\nDefault: `5000`\n\nFor all api. Will be covered by `api.timeout`.\n\n#### success {Array}\n\nDefault: `[]`\n\nFor all api. Will be extended by `api.success`.\n\n#### fail {Array}\n\nDefault: `[]`\n\nFor all api. Will be extended by `api.fail`.\n\n#### ignoreResponse {Boolean}\n\nDefault: `false`\n\nIf response dose not have param which success or fail need, whether to throw an error or not.\n\n#### errorMessage {Object}\n\nThe error message you supply will overwrite default error message by same name.\n\n#### headers {Object}\n\nDefault: `{\n\t'Accept': 'application/json, */*; q=0.01',\n\t'Accept-Charset': 'utf-8'\n}`\n\nFor all api. Will be extended by `api.headers`.\n\n#### dataType {String}\n\nDefault: `Origin`\n\nFor all api. Will be covered by `api.dataType`.\n\n#### rootUrl {String}\n\nDefault: `''`\n\nSet prefix for `api.url`. For all api. Will be covered by `api.rootUrl`.\n\n### Config File Example\n\n```yml\napi:\n-\n  url: //www.123.com/test/test1\n  type: put\n  name: createAlgorithm\n  mode: 'cors'\n  needs:\n    username: String\n    nickname?: String\n  success:\n    - algorithmId\n    - updateTime\n-\n  url: /test/test2\n  type: delete\n  name: checkLogin\n  cache: 'no-cache'\n  timeout: 10000\n  needs:\n    test: Boolean\n  success:\n    - username\n    - avatar\n-\n  url: /test/test3\n  type: post\n  name: editUser\n  isSuccess:\n    status: true\n  needs:\n    username: String\n    id:\n      - Number\n      - String\n-\n  url: /test/:sid/:pid\n  type: get\n  name: getPt\n  needs:\n    sid: Number\n    pid?: Number\nconfig:\n  isSuccess:\n    code: 0\n  ignoreResponse: false\n  headers: {\n    Content-Type: application/x-www-form-urlencoded\n  }\n  fail:\n    - message\n```\n\n## About This Package\n\nThis part is for using this package.\n\n### Options\n\nThe follow options are used for this package, not for yaml config.\n\n#### target {String}\n\nYaml config file path. Should be absolute path or relative to the file you run this command.\n\n#### lang {String}\n\nDefault: `english`\n\nLanguage for error message. Ignore case. Welcome PR \u003e.\u003c\n\n- Chinese\n- English\n\n#### outputFile {String}\n\nThe file path to output result. Should be absolute path or relative to the file which use this package.\n\n#### module {String}\n\nDefault: `commonjs`\n\nThe output file follows the module spec you choose. Ignore case. Welcome PR to add more. Support list:\n\n- CommonJS\n- ES2015\n\n#### browser {Boolean|String}\n\nDefault: `false`\n\nThis option determine the output code could run in browser directly or not.\nIf it's not `false`, it should be a string as a module name for browser global object.\n\nThe CommonJS module will be transform with browserify and ES2015 module will be transform with rollup.\nThen you could use generated module in browser like [Generated Module Usage Example](#user-content-generated-module-usage-example).\n\n#### encoding {String}\n\nDefault: `utf8`.\n\nFile encoding for config file and output file.\n\n### Package Usage Example\n\n```js\nvar api = require('js-api-generator');\nvar result = api({\n    target: 'target yaml path',\n    // other options\n});\n```\n\n## Browser Compatibility\n\n|\t\t| Chrome | Firefox | Edge | IE | Opera | Safari |\n| ----- | ------ | ------- | ---- | -- | ----- | ------ |\n| Output file | 45.0 | 22.0 | Yes | Not support | 32\t| 10.0 |\n| Compile with babel or buble | Yes | Yes | Yes | Depends on polyfill | Yes | Yes |\n\n## Demo\n\nSee `./test/api.yml`.\n\n\n[ci-img]:https://img.shields.io/travis/poppinlp/js-api-generator.svg?style=flat-square\n[ci-url]:https://travis-ci.org/poppinlp/js-api-generator\n\n[dep-img]:https://img.shields.io/david/poppinlp/js-api-generator.svg?style=flat-square\n[dep-url]:https://david-dm.org/poppinlp/js-api-generator\n\n[dev-dep-img]:https://img.shields.io/david/dev/poppinlp/js-api-generator.svg?style=flat-square\n[dev-dep-url]:https://david-dm.org/poppinlp/js-api-generator#info=devDependencies\n\n[npm-ver-img]:https://img.shields.io/npm/v/js-api-generator.svg?style=flat-square\n[npm-dl-img]:https://img.shields.io/npm/dm/js-api-generator.svg?style=flat-square\n[npm-lc-img]:https://img.shields.io/npm/l/js-api-generator.svg?style=flat-square\n[npm-url]:https://www.npmjs.com/package/js-api-generator\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoppinlp%2Fjs-api-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpoppinlp%2Fjs-api-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoppinlp%2Fjs-api-generator/lists"}